5. Collect a payment

Requests a payment from a customer: they receive a confirmation request on their phone (Mobile Money PIN). Headers: Authorization: Bearer sk_… and X-Application-ID: 1.

Collect from a customer

POST/transactionsAPI key + X-Application-ID

Request body

{
  "type": "collection",
  "provider": "orange_money_cm",
  "amount": 5000,
  "currency": "XAF",
  "phone_number": "696246686",
  "idempotency_key": "commande-1234",
  "metadata": {
    "description": "Commande 1234",
    "customer_name": "Nom du client"
  }
}

Call examples (staging)

curl -X POST 'https://dev-aggregator-api.kratospay.com/api/v1/transactions' \
  -H 'Authorization: Bearer sk_test_VOTRE_CLE' \
  -H 'X-Application-ID: 1' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"type":"collection","provider":"orange_money_cm","amount":5000,"currency":"XAF","phone_number":"696246686","idempotency_key":"commande-1234","metadata":{"description":"Commande 1234","customer_name":"Nom du client"}}'

Response 201

{
  "success": true,
  "data": {
    "uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3",
    "type": "collection",
    "provider": "orange_money",
    "status": "pending",
    "amount": "5000.00",
    "currency": "XAF",
    "reference": "MP240101.1234.A56789",
    "external_id": null,
    "phone_number": "696246686",
    "checkout_url": null,
    "metadata": {
      "description": "Commande 1234",
      "customer_name": "Nom du client"
    },
    "expires_at": null,
    "created_at": "2026-11-02T08:00:00Z",
    "updated_at": "2026-11-02T08:00:00Z"
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Collect by bank card

POST/transactionsAPI key + X-Application-ID

For both Mastercard and Visa, use provider: "mastercard". Both networks use this same flow: do not send a phone number or card details; the response provides checkout_url, which you must open so the customer can pay on the secure hosted page. return_url is optional.

Request body

{
  "type": "collection",
  "provider": "mastercard",
  "amount": 25000,
  "currency": "XAF",
  "idempotency_key": "commande-5678",
  "return_url": "https://monsite.com/merci",
  "metadata": {
    "description": "Commande 5678"
  }
}

Response 201

{
  "success": true,
  "data": {
    "uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b4",
    "type": "collection",
    "provider": "mastercard",
    "status": "pending",
    "amount": "25000.00",
    "currency": "XAF",
    "reference": "K7H2M9QXP4R8T1W5Z3NB",
    "phone_number": null,
    "checkout_url": "https://master.kratos-travel.com/?sessionId=SESSION0002..."
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Code	When
422	Invalid amount or currency, card payments not enabled for the account, or payment gateway temporarily unavailable.

After payment, the customer returns to return_url. Never fulfill an order based only on this redirect: wait for transaction.success or check GET /transactions/{uuid}. Possible statuses are pending, success, failed and expired.
Cards do not support payouts or API refunds at this time.

Possible error responses

Code	When
401	Invalid, inactive or expired API key, or key from another environment.
422	Invalid amount, network unavailable or disabled, number not matching the network's country, `idempotency_key` already used by another operation, or payment not initiated (retry in a moment).

Required fields: type, provider, amount, and phone_number for a collection. Other types: disbursement (send), airtime, tv, internet.
The initial status is pending: it is not a failure. Wait for the webhook or fetch the transaction.
Orange Money: fill in metadata.customer_name if you plan to issue refunds.
In test (sk_test_), no money moves and the outcome is simulated.