Payment Intents

A PaymentIntent represents a payment flow. It tracks the lifecycle from creation to completion.

Current implemented route family: /api/v1/payment-intents

The PaymentIntent object

{
  "id": "pi_1a2b3c4d5e",
  "object": "payment_intent",
  "created": 1708300800,
  "livemode": false,
  "amount": 10000,
  "currency": "XOF",
  "status": "requires_payment_method",
  "description": "Order #1234",
  "metadata": {
    "order_id": "order_123"
  },
  "next_action": null,
  "customer": "cus_123"
}

Create a PaymentIntent

POST /api/v1/payment-intents

Parameter	Type	Required	Description
amount	integer:int64	Yes	Amount in the smallest currency unit.
currency	string	Yes	Three-letter ISO currency code, for example XOF.
transaction_country	string	Yes	ISO 3166-1 alpha-2 transaction country code, for example SN, CI, or BJ.
payer_country	string	No	ISO 3166-1 alpha-2 payer country code when different or known.
rail_country	string	No	ISO 3166-1 alpha-2 rail/operator country code.
description	string	No	Human-readable payment description.
metadata	object<string,string>	No	Business metadata. Keys and values must be strings.
customer	string	No	Public ID of an existing customer.
customer_email	string	No	Customer email used to find or create a customer.
customer_phone	string	No	Customer phone used to find or create a customer.

{
  "amount": 10000,
  "currency": "XOF",
  "transaction_country": "SN",
  "description": "Order #1234",
  "metadata": {
    "order_id": "order_123",
    "checkout_session_id": "cs_123"
  },
  "customer_email": "customer@example.com"
}

Country Parameters

transaction_country is required. It defines the primary country context used by country/currency eligibility rules and rail selection.

payer_country and rail_country are optional. Use them only when the payer country or payment rail country must be explicit. All three values are two-character ISO 3166-1 alpha-2 codes.

Metadata

metadata is an object<string,string> for business references such as order_id, cart_id, checkout_session_id, or source.

Non-string values are not returned on the PaymentIntent object. Do not use the reserved keys Description, FailureReason, Environment, or the prefixes country_context., internal., and technical.: they are reserved for platform data and filtered from responses.

Retrieve a PaymentIntent

GET /api/v1/payment-intents/{id}

Parameter	Type	Required	Description
id	string	Yes	Public PaymentIntent ID.

Update a PaymentIntent

PATCH /api/v1/payment-intents/{id}

Parameter	Type	Required	Description
id	string	Yes	Public PaymentIntent ID.
description	string	No	New description.
metadata	object<string,string>	No	Metadata keys to add or replace.

Confirm a PaymentIntent

POST /api/v1/payment-intents/{id}/confirm

Parameter	Type	Required	Description
id	string	Yes	Public PaymentIntent ID.
payment_method.type	string	Yes	Method type, for example mobile_money or card.
payment_method.mobile_money.country	string	Mobile money	ISO 3166-1 alpha-2 country code. Must match the PaymentIntent transaction_country.
payment_method.mobile_money.operator	string	Mobile money	Mobile money operator, for example orange_money, wave, or mtn.
payment_method.mobile_money.msisdn	string	Mobile money	Payer mobile money number.
payment_method.mobile_money.preferred_flow	string	No	Preferred flow when supported by the provider.
payment_method.card.token	string	Card	Card token.
return_url	string	No	URL where the customer should be redirected after payment.

{
  "payment_method": {
    "type": "mobile_money",
    "mobile_money": {
      "country": "SN",
      "operator": "orange_money",
      "msisdn": "+221770000000"
    }
  }
}

Return URL

Use return_url to indicate the page in your application where the customer should return after the payment is completed.

This URL is optional. If it is omitted, Ikawaari uses the default return URL configured in the merchant dashboard when one exists. Otherwise, the customer remains on the Ikawaari status page.

The same return_url is used regardless of the payment outcome. On redirect, Ikawaari adds query parameters so your application can display the right confirmation page:

https://your-site.com/payment/return?status=succeeded&payment_intent=pi_...&operation_id=pi_...

status is typically succeeded or failed. Use payment_intent to retrieve the final status from the API when you need to validate the result server-side.

Confirmation concurrency and idempotency

Confirmation is protected by a platform-side lock. If two confirm calls target the same PaymentIntent at the same time, Ikawaari starts only one active provider confirmation.

• If the PaymentIntent has already moved to a non-confirmable status, such as processing, requires_action, succeeded, or failed, the API returns the current object without calling the provider again.
• If a confirmation is already in progress and the lock cannot be acquired immediately, the API returns 409 Conflict with code: "IKW-RES-003", retryable: true, and the message Payment intent confirmation is already in progress.
• If a database persistence concurrency conflict is detected, the API also returns 409 Conflict with code: "IKW-RES-003" and retryable: true, instead of an internal error.

Clients can retry after a short delay or retrieve the PaymentIntent to display its current status.

Cancel a PaymentIntent

POST /api/v1/payment-intents/{id}/cancel

Parameter	Type	Required	Description
id	string	Yes	Public PaymentIntent ID.

List PaymentIntents

GET /api/v1/payment-intents

Parameter	Type	Required	Description
limit	integer:int32	No	Number of results requested.