Skip to main content

Pay-ins

Last updated: 2026-09-25

Choose a market and inbound method from Catalog and availability, then use either a hosted or direct flow.

The crediting steps below apply to new completions. Historical completed payments retain their requested amount for compatibility; reading them is not new payment confirmation and must not trigger another customer credit.

Hosted pay-in (H2P)​

  1. Initialize the pay-in with the selected market, amount, method, unique merchantReference, and customer return URL.
  2. Store the returned payment order ID and your reference.
  3. When a payment URL is returned, send the customer to it.
  4. Treat the customer return as navigation only. Confirm the result from the latest payment status or a verified webhook.
  5. Credit the customer idempotently once per payment ID, only after PAYMENT_ORDER_STATUS_COMPLETED, using actualAmount, not the originally requested amount. Deduplicate that credit across payment reads and webhook deliveries; another completed observation must not repeat it. See Requested and recognized amounts.

Hosted checkout owns the customer-facing payment step. Your integration still owns reconciliation.

Direct pay-in (H2H)​

  1. Discover any bank or mobile money operator required by the method.
  2. Create the pay-in with the detail block that matches paymentMethod.
  3. Continue the returned redirect or payment instructions.
  4. For ORANGE in a market covered by the Orange OTP contract, continue with OTP when discovery selected ORANGE, the create response returns isOtpAuthRequired: true, and your flow has collected the customer's token. For other operators, treat the field as a general continuation signal and follow the method-specific contract.
  5. Reconcile the latest status through payment reads and webhooks.
  6. After PAYMENT_ORDER_STATUS_COMPLETED, credit actualAmount idempotently once per payment ID, including when the same result arrives through a read and a webhook or through repeated deliveries. Do not use the requested amount or deduct fees from it. See Requested and recognized amounts.

For the complete Orange market list and its 15-minute authorization window, follow Orange OTP continuation.

Display displayMessage only for flows whose customer-facing copy you have reviewed, and render it as plain text. Do not derive status, failure reason, or payment details from it. Retain the create response if you need to keep showing the message from mobileMoneyDetails, because later payment reads do not include that create-response object. Mobile money transfer uses the separate mobileMoneyTransferDetails object, which can be updated in payment reads and webhooks, including its display message and payment instructions.

After a timeout, keep the same reference and reconcile the existing payment. Use Pay-in retry rules to decide whether the create or initialize request can be repeated. A repeated error is not a reason to keep creating new references.

Never send detail blocks for a different payment method. For method-specific steps, see Bank transfer, Mobile money, Mobile money transfer, and Vouchers.

API reference​