Version: 1.0.0

Payment Checkout API

This API initiates an authentication session for the payment Checkout.

The Checkout API is divided into three main categories:

• Basic Operations
  • Sale (Authentication session)
  • Capture request
  • Refund
  • Void
  • Card credit (payout)
• Recurring and Retries
  • Recurring Sale
  • Retry Payment
• Transaction Status
  • Get Transaction status by payment_id
  • Get Transaction status by order_id

Card credit (payout): /api/v1/payment/card/credit

Sends a payout straight to a card without opening the Checkout page. It creates a new payment rather than acting on an existing one, so it is not a post-payment operation. The operation is fixed by the endpoint itself, so there is no operation parameter here, unlike the Authentication Request, which serves several operations.

This endpoint works for cards only. For a payout to another payment method, create a session with operation=credit in the Authentication Request.

Request:

Parameter	Type	Required	Description
merchant_key	string	yes
order_id	string	yes	Flat field, not the nested order object used when creating a session.
order_amount	string	yes	Decimal string with 2 to 4 digits after the dot, greater than zero.
order_currency	string	yes	ISO 4217 code, 3 to 4 uppercase letters.
order_description	string	yes
card_number	string	conditional	Payee card number. Send either card_number or card_token.
card_token	string	conditional	Token from an earlier purchase or debit sent with req_token: true, a single string. The card number, expiry and cardholder name are taken from the token, and the payer is not redirected to Checkout.
payee_first_name / payee_last_name / payee_email / payee_ip	string	optional	Payee details.
hash	string	yes	See Hash signature, Card credit.

Response:

{
  "payment_id": "dc66cdd8-d702-11ea-9a2f-0242c0a87002",
  "result":     "accepted"
}

result=accepted means the payout was accepted for processing, not that it settled. The outcome arrives in a type=credit callback.

Full parameter list, both request examples and the field-level rules: Card credit (payout).

Post-payment operations

The Post-payment operations endpoints act on a payment that has already been initiated through /api/v1/session.

Capture: /api/v1/payment/capture

Captures funds previously authorized by an auth (DMS / two-step) flow.

Request:

Parameter	Type	Required	Description
merchant_key	string	yes
payment_id	string (UUID)	yes	Public payment ID returned by Checkout.
amount	string	yes	Amount to capture (≤ original auth amount). Decimal string, format XXXX.XX.
hash	string	yes	See Hash signature.

Response:

{
  "payment_id":   "63c781cc-de3d-11eb-a1f1-0242ac130006",
  "status":       "settled",
  "trans_status": "SUCCESS",
  "date":         "2020-08-05 07:41:10"
}

Refund: /api/v1/payment/refund

Refunds a settled payment (full or partial; a debit only in full). For a DMS authorization that was not captured (pending), releases the hold instead, for the full amount only.

Request:

Parameter	Type	Required	Description
merchant_key	string	yes
payment_id	string (UUID)	yes
amount	string	no	Refund amount. If omitted, the full payment amount is refunded. For a pending or a debit payment only the full amount is accepted.
hash	string	yes	See Hash signature.

Response:

{
  "payment_id": "63c781cc-de3d-11eb-a1f1-0242ac130006",
  "result":     "accepted"
}

info

The final outcome is delivered via a type=refund callback (see Callbacks).

Void: /api/v1/payment/void

Cancels a settled payment on the same financial day. To release a DMS authorization that was not captured, use Refund.

Request:

Parameter	Type	Required	Description
merchant_key	string	yes
payment_id	string (UUID)	yes
hash	string	yes	See Hash signature.

Response:

{ "payment_id": "...", "status": "void", "date": "..." }

Recurring: /api/v1/payment/recurring

Charges a previously initialized recurring chain. The first payment must be a purchase with recurring_init=true; its callback contains recurring_init_trans_id, recurring_token, and (optionally) schedule_id that you store and replay here.

Request:

Parameter	Type	Required	Description
merchant_key	string	yes
recurring_init_trans_id	string (UUID)	yes	From the initial sale callback.
recurring_token	string	yes	From the initial sale callback.
schedule_id	string	optional	If you use schedules.
order	object	yes	number (string, ≤255), amount (decimal string), description (2–1024). Currency is inherited from the initial payment.
custom_data	object	optional	Overrides custom_data from the initial sale.
hash	string	yes	See Hash signature.

Response:

{
  "status":      "settled",
  "payment_id":  "dc66cdd8-d702-11ea-9a2f-0242c0a87002",
  "schedule_id": "57fddecf-17b9-4d38-9320-a670f0c29ec0",
  "date":        "2020-08-05 07:41:10",
  "order": { "number": "order-1234", "amount": "0.19", "currency": "USD", "description": "Subscription" }
}

On decline the response carries status="declined" and reason="...".

Retry: /api/v1/payment/retry

Retries a recurring payment that received a soft decline. Creates a new RETRY transaction; its outcome is delivered via callback.

Request:

Parameter	Type	Required	Description
merchant_key	string	yes
payment_id	string (UUID)	yes	The payment to retry.
hash	string	yes	See Hash signature.

Response:

{ "payment_id": "63c781cc-de3d-11eb-a1f1-0242ac130006", "result": "accepted" }

result=accepted means the retry was queued; the outcome arrives via callback.

Get transaction status: /api/v1/payment/status

Look up the current state of a payment by either payment_id or order_id.

note

If Cascading Context for Get Status is enabled in Protocol Mappings, the response describes the most recently created payment within the cascade, not necessarily the one you specified.

Request by payment_id:

Parameter	Type	Required	Hash formula
merchant_key	string	yes
payment_id	string (UUID)	yes
hash	string	yes	Hash signature

Request by order_id:

Parameter	Type	Required	Hash formula
merchant_key	string	yes
order_id	string	yes	Your order.number.
hash	string	yes	Hash signature

Response (both variants):

{
  "payment_id": "dc66cdd8-d702-11ea-9a2f-0242c0a87002",
  "date":       "2020-08-05 07:41:10",
  "status":     "settled",
  "reason":     null,
  "card_token": "f5d6a0ab6fcfb6487a39e2256e50fff3c95aaa97075ee5e539bb662fceff4dc1",
  "recurring_token": "e5f60b35485e",
  "schedule_id":     "57fddecf-...",
  "order":   { "number": "order-1234", "amount": "0.19", "currency": "USD", "description": "Important gift" },
  "customer":{ "name": "John Doe", "email": "[email protected]" }
}

Use status polling only as a fallback. The callback is the source of truth; polling adds load and delays your fulfillment.