Skip to main content
POST
Create a transaction
This operation registers a payment request for the authenticated account and returns the references to keep. It only supports Ipay-Payment-Type: mobile (mobile money); other payment methods go through payment by link. The list of methods is in Payouts and fees.
The status returned at creation is not final. Always check the final status on the server side, with Retrieve a transaction or through webhooks, before delivering an order.
  • Validated account. The account must be validated for the target environment, otherwise the API responds 403 without creating a transaction.
  • Environments. Sandbox and Live are two separate accounts, with separate keys: a Sandbox key used with Ipay-Target-Environment: live is refused, and vice versa. See Authentication.
  • transaction_id. This is your own order reference, unique for your account. You will find it under the name external_reference, and it is accepted as an identifier by Retrieve a transaction.
  • Minimum amount. 25 XOF in Live for mobile. The minimum is different in Sandbox: see Sandbox and testing.
  • References to keep. reference is the iMoney Encaissement identifier of the transaction, accepted by the retrieval operations. public_reference is the reference you can show to your customer.

Duplicates and idempotency

There is no idempotency key header. Creation applies duplicate detection at the application level on external_reference, that is, on the transaction_id you send. In Live, a second call with the same value receives 422 ({"status": "failed", "message": "External Reference Not Valid"}) and does not create a second transaction. In Sandbox, the shape of the response to a duplicate is not guaranteed to match the Live one: to be confirmed with support before using it as an automated test assertion.
This detection is not guaranteed under concurrent calls: two requests sent at the same moment with the same transaction_id may both succeed. Generate a unique transaction_id for each attempt, and check the status with Retrieve a transaction before retrying a transaction for which you did not receive a response.

Limits

No rate limit is documented for this operation: to be confirmed with support before bulk sending. The error messages common to all operations are gathered in Errors.

Authorizations

Authorization
string
header
required

Secret key of the Sandbox or Live account

Headers

Ipay-Target-Environment
enum<string>
required
Available options:
sandbox,
live
Ipay-Payment-Type
string
required

Payment method. POST /payments only supports mobile (mobile money). Other payment methods (bank card and other channels) are not used here: they are available through payment links (POST /external_payments). Full list: payment methods.

Allowed value: "mobile"
Example:

"mobile"

Body

application/json

Body required to create a mobile money payment (Ipay-Payment-Type: mobile). The minimum amount is 25 XOF (50 XOF in Sandbox). Below that, the API responds 400 Bad Request: Amount Not Valid. For other payment methods, use payment links.

amount
integer
required

Amount to debit, in XOF (integer). Minimum: 25 XOF in Live, 50 XOF in Sandbox.

Required range: x >= 25
Example:

1000

country
enum<string>
required
Available options:
NE,
BJ
Example:

"NE"

currency
string
required
Allowed value: "XOF"
msisdn
string
required
Example:

"40410000000"

transaction_id
string
required

Unique reference within the account

customer_name
string
required

Response

Transaction registered. The final status must be checked separately.

status
string
required
Example:

"succeeded"

reference
string
required
public_reference
string
required
meta_data
object