Skip to main content
FluxanDeveloper docs
简体中文

Create payment

API contract v1.0.0

createPayment
POST/v1/payments
Required scopespayments:writeIdempotency key required

Creates a Payment that corresponds one-to-one with a merchant order; with confirm=true, it submits the first attempt immediately. (merchant, environment, merchant_order_no) is unique. The merchant and environment are derived from the API key, so the request doesn't carry a merchant ID. The platform saves the Payment and the attempt before sending anything to the provider. Raw card data is used only transiently in the platform's isolated card processing environment and is never stored or logged. If direct card isn't enabled, the API returns 403 capability_disabled. For direct wallet, send payment_method_data.type=wallet. The phone number isn't stored either, and return_url isn't needed. Once the provider confirms the push to the payer, the API returns 201 with status=requires_action and next_action=null; the payer confirms in the wallet app, and you get the result from a webhook or by querying the payment. If the provider's answer isn't clear, the API returns 202 with status=processing, and the payment moves to requires_action once the push is confirmed. If the same order is submitted again while its outcome is unknown, the API returns only the original object or a 409 and doesn't trigger a new transaction. 200 means an idempotent replay, 201 means a new object was created, and 202 means the request was accepted but the outcome is pending confirmation. A 2xx never means the charge succeeded: rely on status or a webhook whose signature you've verified.

Request headers

Request headersRequiredFormatDescription
AuthorizationYesBearer <API_KEY>

Server-side key, to be used only on the merchant's server. The merchant and environment are derived from the key. A missing, invalid, revoked or expired key returns 401.

Content-TypeYesapplication/json

The request body is UTF-8 encoded JSON.

Idempotency-KeyYes1–255 visible ASCII characters

Idempotency key, 1–255 visible ASCII characters. The scope is merchant, environment, method and path: with the same key and matching core business parameters, the original business object is reused, and conflicting parameters return 409 idempotency_conflict. Use one key per submission, and reuse the same key when you retry after a network error; use a new key for a new submission, such as a card change. For concurrent requests with the same key, only one request gets to run, and the others wait for its transaction to commit and then return the same object (200). If the wait times out, the API returns 409 operation_in_progress (retryable=true); retry later with the original key. A request rejected with 400, 401, 403 or 422 doesn't consume the idempotency key; fix it and submit with a new key.

Request body

JSON object CreatePaymentRequest

NameTypeRequiredDescription
merchant_order_no
stringRequired

Merchant order ID: 1-64 letters, numbers, periods, underscores, colons or hyphens. It's unique within one merchant and environment, case-sensitive as sent, and whitespace isn't trimmed automatically.

Constraints: Format ^[A-Za-z0-9._:-]{1,64}$

Example: ORDER-DEMO-001

amount
integer(int64)Required

Order amount, in the smallest currency unit; it must fit the currency and limit settings. When the currency's provider takes whole units only (such as PKR), it must be a whole number of currency units; otherwise confirming (confirm=true or confirmPayment) returns 400 invalid_request (field=amount).

Constraints: ≥ 1

Example: 10000

currency
stringRequired

An enabled currency, as an uppercase three-letter code.

Constraints: Format ^[A-Z]{3}$

Example: USD

confirm
booleanNo

When true, the payment is attempted immediately.

Constraints: Default false

Example: true

payment_method_data
PaymentMethodData
Condition: Send either this or payment_method_id when confirm=true; don't send it when confirm=false

Payment method data. It's accepted only when confirm=true. Send either this or payment_method_id. type=card: card is required, and only merchants with the direct card capability are accepted. Raw card fields are used only transiently in the platform's isolated card processing environment and are never written to a database, cache, queue, log or error report. type=wallet: wallet is required and card isn't allowed, and only merchants with the direct wallet capability are accepted. return_url isn't needed and the payer isn't redirected. Once the provider confirms the push to the payer, the payment moves to requires_action with next_action set to null; the payer confirms in the wallet app, and you get the result from a webhook or by querying the payment.

type
stringRequired

Payment method type: card for direct card; wallet for direct wallet.

  • card
  • wallet
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: card

card
CardDetailsNo

Card details. Required when type=card.

wallet
WalletDetailsNo

The wallet and the payer's phone number. Required when type=wallet.

payment_method_id
string
Condition: Send either this or payment_method_data when confirm=true

A scoped payment credential supported by the adapter. It must belong to the current environment, provider account and this merchant. It doesn't mean the platform provides a permanent card vault.

Constraints: Length 1–255

Example: pm_demo_001

return_url
string(uri)
Condition: Required when confirm=true

The merchant's return URL after authentication completes. It must match a redirect URL rule registered for the current environment: the match covers the scheme, host (exact or one-level wildcard), port and path prefix (by path segment), and the query string and fragment aren't part of the match. When the platform redirects the payer back, it uses this URL exactly as provided and appends no parameters.

Constraints: Max length 2048

Example: https://merchant.example/payment/return

description
stringNo

Order summary. It must not contain sensitive information such as card numbers.

Constraints: Max length 256

Example: Example order

customer_reference
stringNo

Merchant-side customer reference. A name or full contact details aren't required.

Constraints: Max length 128

Example: CUSTOMER-DEMO-001

billing_details
BillingDetails
Condition: Required if the current provider's capabilities demand it; if it's missing, the API returns 400 before anything is submitted to the provider, and error.field names the field

Cardholder details. Whether they're required depends on the current provider account's capabilities; if they're missing, the API returns 400 before submitting to the provider, and error.field names the field (for example billing_details.phone or billing_details.address.postal_code).

name
stringNo

Cardholder name.

Constraints: Max length 256

Example: Test Customer

email
string(email)No

Cardholder email address.

Constraints: Max length 254

Example: customer@example.com

phone
stringNo

Payer phone number, preferably with the country code. It may contain spaces, hyphens, periods and parentheses; without them it must be 6–15 digits (the E.164 maximum). It must not contain a card number.

Constraints: Format ^\+?[0-9 ().-]{6,32}$Length 6–32

Example: +1 415 555 0100

address
AddressNo

Billing address.

browser_info
BrowserInfo
Condition: Required if the current provider's capabilities demand it; if it's missing, the API returns 400 before anything is submitted to the provider, and error.field names the field

The payer's real browser context, used for 3DS. It must come from the payer's browser and can't be replaced with merchant server information. Whether it's required depends on the capabilities of the current provider adapter; if required information is missing, a clear error is returned before anything is submitted to the provider.

user_agent
stringNo

The payer's browser User-Agent.

Constraints: Max length 2048

Example: Mozilla/5.0

accept_header
stringNo

The Accept request header of the payer's browser.

Constraints: Max length 2048

Example: text/html,application/xhtml+xml

language
stringNo

Browser language (BCP 47).

Constraints: Max length 35

Example: zh-CN

screen_width
integer(int32)No

Constraints: ≥ 0

Example: 1366

screen_height
integer(int32)No

Constraints: ≥ 0

Example: 768

color_depth
integer(int32)No

Constraints: 1–48

Example: 24

timezone_offset_minutes
integer(int32)No

Time zone offset in minutes, following the sign convention of JavaScript's getTimezoneOffset(). For example, UTC+8 is -480.

Constraints: -840–720

Example: -480

javascript_enabled
booleanNo

Example: true

ip_address
stringNo

The payer's IPv4 or IPv6 address. Resolve it through a trusted proxy chain, and don't use the merchant server's IP address in its place.

Constraints: Max length 45

Example: 203.0.113.10

metadata
objectNo

Custom key-value pairs set by the merchant: up to 20 keys. A key can be up to 40 characters, and a value is a string of up to 200 characters. Don't put sensitive data such as card numbers in it. The platform checks for such data and rejects the request.

Constraints: Up to 20 keysMax value length 200

Example: {"business_order_type":"one_time_purchase"}

Request example

Create and confirm with a scoped payment credential

curl
curl -X POST 'https://api.fluxan.co/v1/payments' \
  -H 'Authorization: Bearer <TEST_SERVER_API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <UNIQUE_OPERATION_KEY>' \
  -d '{
  "merchant_order_no": "ORDER-DEMO-001",
  "amount": 10000,
  "currency": "USD",
  "confirm": true,
  "payment_method_id": "pm_demo_001",
  "return_url": "https://merchant.example/payment/return",
  "description": "Example order",
  "customer_reference": "CUSTOMER-DEMO-001",
  "billing_details": {
    "name": "Test Customer",
    "email": "customer@example.com"
  },
  "browser_info": {
    "user_agent": "Mozilla/5.0",
    "accept_header": "text/html,application/xhtml+xml",
    "language": "zh-CN",
    "screen_width": 1366,
    "screen_height": 768,
    "color_depth": 24,
    "timezone_offset_minutes": -480,
    "javascript_enabled": true,
    "ip_address": "203.0.113.10"
  },
  "metadata": {
    "business_order_type": "one_time_purchase"
  }
}'

Placeholders to replace

  • <TEST_SERVER_API_KEY>: Test-environment server API key, created on the "API Key" page of the merchant portal
  • <UNIQUE_OPERATION_KEY>: The idempotency key you generate for this request (for example, a UUID); reuse the same key when you retry after a network error

Create and confirm with direct card (card fields are placeholders)

curl
curl -X POST 'https://api.fluxan.co/v1/payments' \
  -H 'Authorization: Bearer <TEST_SERVER_API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <UNIQUE_OPERATION_KEY>' \
  -d '{
  "merchant_order_no": "ORDER-DEMO-002",
  "amount": 10000,
  "currency": "USD",
  "confirm": true,
  "payment_method_data": {
    "type": "card",
    "card": {
      "number": "<UPSTREAM_TEST_CARD_NUMBER>",
      "exp_month": 12,
      "exp_year": 2030,
      "cvc": "<UPSTREAM_TEST_CVC>"
    }
  },
  "return_url": "https://merchant.example/payment/return",
  "description": "Example order",
  "customer_reference": "CUSTOMER-DEMO-002",
  "billing_details": {
    "name": "Test Customer",
    "email": "customer@example.com"
  },
  "browser_info": {
    "user_agent": "Mozilla/5.0",
    "accept_header": "text/html,application/xhtml+xml",
    "language": "zh-CN",
    "screen_width": 1366,
    "screen_height": 768,
    "color_depth": 24,
    "timezone_offset_minutes": -480,
    "javascript_enabled": true,
    "ip_address": "203.0.113.10"
  }
}'

Placeholders to replace

  • <TEST_SERVER_API_KEY>: Test-environment server API key, created on the "API Key" page of the merchant portal
  • <UNIQUE_OPERATION_KEY>: The idempotency key you generate for this request (for example, a UUID); reuse the same key when you retry after a network error
  • <UPSTREAM_TEST_CARD_NUMBER>: Test card number. The test environment has a single generic test card, shown under "API docs and testing guide" in the merchant portal after you sign in
  • <UPSTREAM_TEST_CVC>: Test card CVC, shown in the merchant portal together with the test card number

Create and confirm a direct wallet payment (the phone number is a placeholder)

curl
curl -X POST 'https://api.fluxan.co/v1/payments' \
  -H 'Authorization: Bearer <TEST_SERVER_API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <UNIQUE_OPERATION_KEY>' \
  -d '{
  "merchant_order_no": "ORDER-DEMO-003",
  "amount": 150000,
  "currency": "PKR",
  "confirm": true,
  "payment_method_data": {
    "type": "wallet",
    "wallet": {
      "provider": "easypaisa",
      "phone": "03001234567"
    }
  },
  "customer_reference": "CUSTOMER-DEMO-003",
  "browser_info": {
    "ip_address": "203.0.113.10"
  }
}'

Placeholders to replace

  • <TEST_SERVER_API_KEY>: Test-environment server API key, created on the "API Key" page of the merchant portal
  • <UNIQUE_OPERATION_KEY>: The idempotency key you generate for this request (for example, a UUID); reuse the same key when you retry after a network error

Note

Server API keys must only be used on your own server, so the docs site doesn't offer interactive API testing. Get a test key: API Key page in the merchant portal (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer)

Responses

Idempotent replay: the idempotency key is the same and the core business parameters match, so the API returns the latest state of the original Payment and doesn't execute a second time.

Replay with the same key: the latest state of the original Payment is returned, and nothing is executed a second time
{
  "id": "pay_demo_001",
  "merchant_order_no": "ORDER-DEMO-001",
  "environment": "test",
  "amount": 10000,
  "currency": "USD",
  "status": "succeeded",
  "resolution_status": "known",
  "captured_amount": 10000,
  "refunded_amount": 0,
  "refund_returned_amount": 0,
  "refund_reserved_amount": 0,
  "refund_status": "none",
  "authentication_status": "authenticated",
  "reconciliation_status": "pending",
  "upstream_receipt_status": "not_received",
  "latest_attempt_id": "pat_demo_001",
  "attempt_count": 1,
  "version": 4,
  "next_action": null,
  "failure": null,
  "description": "Example order",
  "customer_reference": "CUSTOMER-DEMO-001",
  "metadata": {
    "business_order_type": "one_time_purchase"
  },
  "card": {
    "brand": "visa",
    "last4": "1234"
  },
  "created_at": "2026-09-23T09:00:00Z",
  "succeeded_at": "2026-09-23T09:04:30Z",
  "expires_at": "2026-09-23T09:30:00Z",
  "request_id": "req_demo_002"
}

Response fields

Returns an object. See the object section for field descriptions.

NameTypeRequiredDescription
id
stringRequired

Platform payment ID.

Example: pay_demo_001

merchant_order_no
stringRequired

Merchant order ID, case-sensitive as sent.

Example: ORDER-DEMO-001

environment
stringRequired

Environment: test is the test environment and live is the live environment. Test and live objects are isolated from each other.

  • test
  • live
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: test

amount
integer(int64)Required

Order amount, in the smallest currency unit. It can't be changed after the first submission to the provider.

Constraints: ≥ 1

Example: 10000

currency
stringRequired

Uppercase three-letter currency code.

Constraints: Format ^[A-Z]{3}$

Example: USD

status
stringRequired

Payment status. Clients must not treat an unknown status as success.

  • created: the order has been created and no valid charge attempt has been submitted yet; new attempts are allowed within the validity period
  • processing: submitted and being processed, or the outcome isn't confirmed yet; new attempts aren't allowed
  • requires_action: the current attempt needs the payer to complete an action such as authentication. When next_action isn't null, send the payer to that URL; when it's null, the payer's action isn't in the browser (direct wallet: the payer confirms in the wallet app). New attempts aren't allowed
  • failed: the latest attempt clearly failed; this is not a terminal state, and an explicit retry is possible when the deadline, attempt limit and risk conditions are met
  • succeeded: payment confirmed as successful
  • canceled: cancellation confirmed as safe
  • expired: no unresolved attempt, and the order has expired and closed
  • created: The order has been created and no valid charge attempt has been submitted yet; new attempts are allowed within the validity period
  • processing: Submitted and being processed, or the outcome isn't confirmed yet; new attempts aren't allowed
  • requires_action: The current attempt needs the payer to complete an action such as authentication. When next_action isn't null, send the payer to that URL; when it's null, the payer's action isn't in the browser (direct wallet: the payer confirms in the wallet app). New attempts aren't allowed
  • failed: The latest attempt clearly failed; this is not a terminal state, and an explicit retry is possible when the deadline, attempt limit and risk conditions are met
  • succeeded: Payment confirmed as successful
  • canceled: Cancellation confirmed as safe
  • expired: No unresolved attempt, and the order has expired and closed
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: requires_action

resolution_status
stringRequired

Outcome confirmation.

  • known: outcome confirmed
  • needs_query: outcome unknown; the platform is running a status query against the provider using the original identifiers
  • manual_review: past the automatic query window and handed over to manual follow-up; never marked as failed automatically
  • known: Outcome confirmed
  • needs_query: Outcome unknown; the platform is running a status query against the provider using the original identifiers
  • manual_review: Past the automatic query window and handed over to manual follow-up; never marked as failed automatically
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: known

captured_amount
integer(int64)Required

The amount confirmed as captured; equal to amount on success.

Constraints: ≥ 0

Example: 0

refunded_amount
integer(int64)Required

The confirmed effective refunded principal: the total of successful refunds minus confirmed refund returns. It excludes refunds that are still processing and platform exception refunds.

Constraints: ≥ 0

Example: 0

refund_returned_amount
integer(int64)Required

The cumulative refund principal confirmed as returned.

Constraints: ≥ 0

Example: 0

refund_reserved_amount
integer(int64)Required

Principal reserved for refunds that are processing.

Constraints: ≥ 0

Example: 0

refund_status
stringRequired

Refund summary status, derived from refunded_amount (the effective refunded principal): none, partial, full.

  • none
  • partial
  • full
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: none

authentication_status
stringNullableRequired

The 3DS authentication status of the current attempt, taken from the authentication session status: not_required, pending, challenge, authenticated, failed, abandoned, expired. Tolerate new values. Successful authentication (authenticated) doesn't mean the charge succeeded, so don't use it to decide the payment outcome. It's null when there is no attempt yet or the attempt hasn't entered authentication.

Example: challenge

reconciliation_status
ReconciliationStatusRequired

The progress of the platform's funds processing, for reconciliation reference only. It doesn't indicate whether the payment succeeded or when you'll be paid out.

  • pending
  • matched
  • difference
  • resolved
  • More values may be added in the future. Don't treat a status you don't recognize as success.
upstream_receipt_status
UpstreamReceiptStatusRequired

The progress of the platform's funds processing, for reconciliation reference only. It doesn't indicate whether the payment succeeded or when you'll be paid out.

  • not_received
  • partially_received
  • received
  • reversed
  • More values may be added in the future. Don't treat a status you don't recognize as success.
latest_attempt_id
stringNullableRequired

ID of the latest payment attempt; null if no attempt has been submitted yet.

Example: pat_demo_001

attempt_count
integer(int32)Required

The number of attempts started. The default maximum is 3.

Constraints: ≥ 0

Example: 1

version
integer(int64)Required

Object version, which increases with every effective business change. Compare versions to discard older events, and don't order events by status name.

Constraints: ≥ 1

Example: 2

next_action
NextActionNullableRequired

The action the payer must complete when status=requires_action; null in all other cases. It's also null for a direct wallet requires_action: the payer confirms in the wallet app, with no redirect.

type
stringRequired

The initial release of the public API exposes only redirect_to_url. Clients must tolerate types that are added in the future.

  • redirect_to_url
  • More values may be added in the future. Don't treat a status you don't recognize as success.

Example: redirect_to_url

authentication_session_id
stringRequired

Authentication session ID, linked to a specific payment attempt.

Example: auth_demo_001

url
string(uri)Required

The URL of the platform's authentication page.

Example: https://pay.fluxan.example/auth/<SHORT_LIVED_TOKEN>

expires_at
string(date-time)Required

The time the authentication access expires (10 minutes at most).

Example: 2026-09-23T09:10:00Z

failure
PaymentFailureNullableRequired

The reason when the attempt that latest_attempt_id points to has clearly failed; otherwise null.

code
stringRequired

Failure reason code.

Example: card_declined

message
stringRequired

Sanitized description.

Example: The issuer declined this transaction.

attempt_id
stringRequired

ID of the failed payment attempt.

Example: pat_demo_001

description
stringNo

Order summary.

Constraints: Max length 256

Example: Example order

customer_reference
stringNo

Merchant-side customer reference.

Constraints: Max length 128

Example: CUSTOMER-DEMO-001

metadata
objectNo

Custom key-value pairs set by the merchant: up to 20 keys. A key can be up to 40 characters, and a value is a string of up to 200 characters. Don't put sensitive data such as card numbers in it. The platform checks for such data and rejects the request.

Constraints: Up to 20 keysMax value length 200

Example: {"business_order_type":"one_time_purchase"}

card
CardSummaryNullableRequired

Masked details of the card used in the latest attempt; null when there are no card details yet.

brand
stringRequired

Card brand.

Example: visa

last4
stringRequired

Last four digits of the card number.

Constraints: Format ^[0-9]{4}$

Example: 1234

created_at
string(date-time)Required

Creation time.

Example: 2026-09-23T09:00:00Z

succeeded_at
string(date-time)NullableRequired

The time the payment was confirmed as successful; null if it hasn't succeeded.

Example: null

expires_at
string(date-time)Required

The deadline for starting a new attempt, fixed at creation (by default 30 minutes after creation; the platform can adjust it to between 5 and 120 minutes, so go by this field). Expiry only closes the entry point for new attempts. It doesn't invalidate a payment that was already submitted.

Example: 2026-09-23T09:30:00Z

request_id
stringRequired

Unique identifier of this request, used for troubleshooting and support.

Example: req_demo_001

Possible error codes

HTTPError codeWhen it occursHow to handle
400invalid_requestIdempotency-Key is missing; the order ID contains invalid characters; payment_method_data and payment_method_id are submitted together; confirm=false carries card details; confirm=true has no return_url (direct wallet doesn't need one); the wallet phone number isn't a valid 11-digit number starting with 03; a checkout session request sends both groups of identity parameters, or neither; a browser_info / billing_details field the provider requires is missing; the currency's provider takes whole units only (such as PKR) but amount has a fraction; a disbursement's payee details (payee.account, payee.name, payee.bank_code) or customer_ip are invalid; the cursor, time format or limit is invalidFix the request according to error.field and resubmit it; don't charge again automatically
400sensitive_data_rejectedDigits that look like a card number, or similar data, appear in description or metadata; a disbursement's payee.name is checked the same wayRemove the sensitive content and resubmit; check why your system wrote card data into these fields
403capability_disabledDirect card isn't enabled; direct wallet isn't enabled; the payment or refund request capability has been turned off; the currency isn't enabled; the disbursements capability isn't enabled in the current environmentUse hosted checkout instead, or contact platform Operations
403merchant_not_activeThe merchant has been suspended or closed; callbacks, queries and notifications for business that was already accepted aren't affectedContact platform Operations
409idempotency_conflictThe key was reused but the amount, currency, order ID or similar parameters differ; for disbursements, the same key with any request field different (payee details included)An integration defect: check how idempotency keys are generated; don't replay the original key with changed parameters; use a new key for a new operation. A disbursement conflict carries related_resource_id, pointing to the disbursement already accepted with this key: retrieve it first, and don't pay another one
409operation_in_progressRequests with the same key were sent concurrentlyRetry later with the same key, or retrieve related_resource_id; don't switch to a new key
409payment_in_progressCalling confirm again while an attempt is in flight (processing / requires_action), or resubmitting the same order with a new keyRetrieve the Payment that related_resource_id points to and continue according to its status (guide the payer through authentication or wait for the result); don't create a new order
409order_no_conflictA different idempotency key is used with the same merchant order IDRetrieve related_resource_id; if you really need to collect payment again and the original payment is closed, use a new order ID
422currency_not_supportedThe intersection of the merchant's settings and the provider's capabilities doesn't include the currency; for disbursements: the currency isn't enabled for the merchant, has no available disbursement channel, or has no disbursement limits or disbursement rate configuredUse an enabled currency or contact platform Operations
422amount_out_of_rangeBelow the minimum or above the maximum amount per payment, or over the daily cumulative limit; for disbursements, below the per-disbursement minimum, above the per-disbursement maximum, or over the daily amount or daily count; the error doesn't return the specific thresholdsAdjust the amount or contact the platform
422card_brand_not_supportedThe card brand isn't in the overlap between the merchant's configuration and the provider's capabilitiesAsk the payer to use another card
422fee_exceeds_amountThe amount is too small, and the fee calculated from the rate exceeds it; for disbursements, the amount isn't greater than the fee calculated from the disbursement rateIncrease the amount or contact the platform to adjust the configuration
422payment_method_unusablepayment_method_id doesn't belong to the current environment, provider account or this merchantGet a new payment credential
422url_not_allowedreturn_url / cancel_url doesn't match a registered redirect URL ruleRegister it on the redirect URL allowlist page in the merchant portal, then resubmit
422risk_rejectedThe request matched a basic rule such as a risk list, which disbursements are checked against too; the specific rule and threshold aren't disclosedDon't try to work around it; contact the platform if you have questions
503temporarily_unavailableThe platform has paused new transactions on this channel, or paused disbursements; the response doesn't give the internal reasonRetry later with the original idempotency key; this request created no Payment or charge; if it keeps happening, contact platform Operations
401unauthenticatedCommonNo Authorization header was sent; the key was copied incompletely; the old key expired after a rotation; the key was revokedCheck your credentials: on the API Key page in the merchant portal, verify the key's status and environment
403forbiddenCommonCreating a refund with a read-only key; creating or retrieving a disbursement with a key that lacks the disbursement scope; calling getEvent without the read scope for the event's business area; if the request's source IP isn't on the key's allowlist, the more specific ip_not_allowed is returnedUse a key that has the required scope; don't work around the restriction
429rate_limitedCommonA rate limit per merchant and per key; switching keys doesn't get around the merchant's overall limit; disbursement creation is counted separately per merchantWait for Retry-After seconds, then retry with the original idempotency key
500internal_errorCommon—Retry with the original idempotency key, or query by merchant order ID / refund ID / merchant disbursement ID; never charge again with a new key
502 / 503upstream_unavailableCommonA provider or platform dependency failed, and the platform can't confirm whether this request took effect; not the same as the disbursement failure code upstream_unavailable, despite the nameSame as above

Notes

  • (merchant, environment, merchant_order_no) is unique. If you use a different idempotency key with the same order ID, the platform doesn't create a second payment (it returns the existing object or 409 order_no_conflict).
  • Order IDs are case-sensitive and kept exactly as sent, with no whitespace trimming. Only letters, numbers, periods, underscores, colons and hyphens are allowed, and any other character is rejected outright.
  • With confirm=false, the request doesn't accept card details. Direct card requires the platform to enable the "direct card" capability for you. Otherwise the API returns 403 capability_disabled.
  • When payment_method_data.type is wallet, this is a direct wallet collection. The platform must enable the "direct wallet" capability, return_url isn't needed, and browser_info.ip_address is required. Once the provider confirms the push, the API returns 201 requires_action with next_action set to null.
  • The request has no fields for fees, settleable amounts and the like, and doesn't accept them.
  • You can't change the amount after it has been submitted to the provider. To change it, close the original payment, then create a new one with a new order ID.
  • description and metadata must not contain sensitive data such as card numbers. A match returns 400 sensitive_data_rejected.

Warning

200, 201 and 202 don't mean the charge succeeded. Rely on status=succeeded or a payment.succeeded event whose signature you've verified. A 202 means the outcome is unknown, so don't resubmit with a new key.

Was this page helpful?