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
• Recurring and Retries
  • Recurring Sale
  • Retry Payment
• Transaction Status
  • Get Transaction status by payment_id
  • Get Transaction status by order_id

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 an already-settled payment (full or partial).

Request:

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

Response:

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

info

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

Void: /api/v1/payment/void

Cancels an authorized but not-yet-settled payment (releases the hold).

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.