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	Return URL for redirected flows.

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

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.