Build Developer

Mastercard Transaction Flow for CaaS Clients

Simplified Process Overview

overview

The diagram above illustrates the process for a Mastercard transaction involving a Cardholder, Merchant, Mastercard, Build, and the Build Customer (who manages the card program). Crucially, this process requires the Build Customer's active participation in the authorization decision, which directly impacts the success or failure of the card transaction at the point of sale.

Authorization Phase (Real-Time):

The process starts when a Cardholder uses their card at a Merchant.
The Merchant sends an authorization request to Mastercard.
Mastercard routes this request to Build.
Build generates a corresponding order and immediately sends a real-time authorization webhook to the Customer's system.
The Customer must process this webhook and respond to Build with an approval or decline decision within the required timeframe. This decision by the Customer is critical as it determines whether the transaction will be approved or declined.
Build relays the Customer's response back to Mastercard.
Mastercard informs the Merchant of the transaction outcome.
Finally, the Merchant notifies the Cardholder.
This entire authorization process happens in near real-time.

Settlement Phase (Batch Process):

While authorization is immediate, the actual movement of funds (settlement) happens later.
Build processes relevant settlement data to the Customer. The Customer acknowledges receipt.
Due to the operational characteristics of the Mastercard network, the final settlement of funds typically occurs between T+1 and T+14 working days after the initial transaction authorization (where 'T' is the day of authorization).

Authorization

A synchronous webhook is used to enable real-time authorizations, allowing customer to approve or decline authorization requests instantly as they occur.

Responding to Authorization Requests

When Build receives a Mastercard authorization request, it sends a real-time webhook to the customer's system. This authorization webhook includes the corresponding order_no. After processing the authorization, customer will need to pay attention to the related Order according to the order_no. Please see Card Order for details on handling authorization information and its relationship with Orders.

Customer must respond within 1500 milliseconds to approve/decline the transaction.

Request Payload

name	description	type	example
auth_amount	auth amount	BigDecimal	128.88/-128.88
auth_currency	the currency of auth amount	String	AUD
uid	uid of the card holder	String	1808026787681538048
card_id	card identity	String	ETLPzgGfSzg-ef
create_time	transaction time	Long	1724783070549
merchant_name	card payment merchant name	String	PELICANA
id	card transaction id	String	ETLPzgGfSzDTTLQuKEvVlssjq5mer
order_no	card order no	String	1828633042242514944
transaction_type	transaction type	String	PURCHASE
tx_direction	transaction direction	String	CREDIT/DEBIT
acquiring_amount	acquiring amount	BigDecimal	48.47
acquiring_currency	acquiring currency	String	USD
version	version of message	String	v1.0

version

Distinguish webhook versions using the version field. The currency version is v1.0.

transaction_type

Value	Description
PURCHASE	This is the most common type of card swipe, used for purchasing goods or services
REFUND	After the cardholder returns the goods, the merchant will refund the amount to the card account
PRE_AUTH	Commonly used in industries such as hotels and car rentals, where the merchant will first freeze a portion of the amount and then settle the actual consumption later.
WITHDRAW	The cardholder withdraws cash at an ATM
OTHER	Other transactions that do not fall into the above categories, such as installment, etc.

tx_direction

Value	Description
CREDIT	Credit direction, i.e., adding money
DEBIT	Debit direction, i.e., deducting money

Example

When a user taps their card at a merchant, the merchant will initiate an authorization request to the Scheme. The Scheme will forward the request to Build. Build will perform checks such as verifying the card status and checking if the account balance is sufficient.

After passing the checks, Build will forward the request to the customer's system for joint authorization. The customer's system will decide whether to approve or reject the request based on business logic. The customer's system needs to respond to Build within 1500 milliseconds.

The real-time authorization webhook is as follows:

{
  "auth_amount": -18.88,
  "auth_currency": "AUD",
  "uid": "1808026787681538048",
  "card_id": "ETLPzgGfSzg-ef",
  "create_time": 1724783070549,
  "merchant_name": "UBER",
  "id": "ETLPzgGfSzDTTLQuKEvVlssjq5mer",
  "order_no": "1828633042242514944",
  "transaction_type": "PURCHASE",
  "version": "v1.0",
  "acquiring_amount": 18.88,
  "acquiring_currency": "AUD",
  "tx_direction": "DEBIT"
}

Card Order

Every authorization processed in the system is linked to a Card Order, which reflects the full lifecycle of the transaction. The Card Order tracks status changes based on the transaction’s progress—from initial approval to final settlement or cancellation.

Card Order Statuses

Status	Description
`PENDING`	The order has been successfully created and the transaction is authorized but not yet settled. The authorized amount is held/frozen on the cardholder's account.
`COMPLETED`	The transaction has been successfully captured/settled. The authorized amount has been confirmed and will be included in the settlement process.
`CANCELLED`	The order is voided due to either an authorization reversal or expiration. The hold on funds is released and no settlement will occur.
`FAILED`	The authorization failed (e.g., due to insufficient funds or fraud rules). No funds are held, and no transaction is settled.

Authorization & Card Order

Once an authorization is processed (whether approved or declined), a Card Order is generated to track its lifecycle. All subsequent operations—such as capture, reversal, refund, or expiration—are handled and updated through the Card Order.

Developers should track the order_no returned in the authorization response to determine the transaction’s current and final status.

card order state

Authorization Event	Time	Card Order Status
Authorization request is awaiting response	-	No card order created yet
Authorization is declined	Immediately	`FAILED`
Authorization is approved	Immediately	`PENDING`
Full Refund authorization for existing order is approved and cancels an existing order	Immediately	Full Refund for existing card order is updated to `CANCELLED`. Full refund means that the amount of refund is equal to the correlated debit authorization. e.g. if the order_amount of existing card order is -10USD, a Full refund should be +10USD
Credit/Refund Authorization ApprovedOccurs for partial refunds, refunds after settlement, or standalone credits. Build may not link it to a specific debit, or it's linked but not a full reversal.	Immediately or up to T+14 working days.	New card order in `PENDING` status.
Refund authorization is declined	Immediately	New Failed Order generated, please avoid this.
Transaction is settled (captured)	T+1 to T+14 working days after authorization.	Card order transitions from `PENDING` to `COMPLETED`
Authorization expires (e.g., not captured in time)	Up to T+14 working days. Upon detection of expiration	Card order transitions from `PENDING` to `CANCELLED`

Special Case

Refunds

Refunds are also a form of authorization in the Mastercard transaction flow. Based on the context, they behave as follows:

If the refund targets an existing PENDING card order, it cancels the order (status becomes CANCELLED).
If the refund is processed as a standalone transaction (e.g., refund after settlement), it creates a new card order in PENDING status.
If the refund is declined, no changes are made to existing card orders.New Failed Order generated.

To understand which behavior occurred, use the order_no in the authorization response and check the updated status.

The order_amount of a refund authorization is expected to be greater than 0.

Settlement without Prior Authorization

In rare circumstances, transactions initiated by specific types of merchants (e.g., certain transit, bill payments) may bypass the pre-authorization step and proceed directly to settlement.
In such cases, the order is created directly with the COMPLETED status, skipping the PENDING phase. This is represented in the diagram by the path directly from Start to COMPLETED.

Request payload for Card Order webhook:

{
   "id": "17443690760031910648503412862976",
   "order_no": "1910648503136038912",
   "uid": "1910540360908541952",
   "card_id": "ETLPzgGfSzg-gfo",
   "order_amount": -8.11,
   "order_status": "PENDING",
   "transaction_type": "PURCHASE",
   "merchant_name": "KFC65",
   "create_time": 1744369075982,
   "update_time": 1744369075982,
   "related_order_no": "",
   "card_present": false,
   "country": "CHN",
   "city": "Mount Buller2",
   "mcc": "7999",
   "acquiring_currency": "USD",
   "acquiring_amount": 8.11,
   "order_currency": "USD",
   "version": "v1.0",
   "tx_direction": "DEBIT"
}

name	description	type	example
id	message id	String	17295916968821828633042242514988
order_no	order id	String	1828633042242514944
uid	uid	String	1703683603805798401
card_id	card id	String	ETLPzgGfSzg-gp
order_currency	order amount currency	String	AUD
order_amount	order amount	BigDecimal	-77.70
order_status	order status	String	PENDING
transaction_type	card payment transaction type	String	PURCHASE
merchant_name	card payment merchant name	String	COSTCO MARSDEN PARK
create_time	order create time	Long	1725852671294
update_time	order update time	Long	1725851396769
acquiring_amount	acquiring amount	BigDecimal	48.47
acquiring_currency	acquiring currency	String	USD
card_present	whether card present	Boolean	true
country	transaction country	String	AUS
city	transaction city	String	Sydney
mcc	transaction mcc	String	5786
tx_direction	transaction direction	String	CREDIT or DEBIT
related_order_no	related order numbers	String	1839607950353510400,1839607408550096896
version	version of message	String	v1.0

version

Distinguish webhook versions using the version field. The currency version is v1.0.

Card Order Webhook Example

PENDING state

{
"id": "17443690760031910648503412862976",
"order_no": "1910648503136038912",
"uid": "1808026787681538048",
"card_id": "ETLPzgGfSzg-et",
"order_amount": -12.88,
"order_status": "PENDING",
"transaction_type": "PURCHASE",
"merchant_name": "KFC65",
"create_time": 1744369075982,
"update_time": 1744369075982,
"related_order_no": "",
"card_present": true,
"country": "CHN",
"city": "Mount Buller2"
"mcc": "7999",
"acquiring_currency": "AUD",
"acquiring_amount": 12.88,
"order_currency": "AUD",
"version": "v1.0",
"tx_direction": "DEBIT"
}

COMPLETED state

{
"id": "17443690760031910648503412862976",
"order_no": "1910648503136038912",
"uid": "1808026787681538048",
"card_id": "ETLPzgGfSzg-et",
"order_amount": -12.88,
"order_status": "COMPLETED",
"transaction_type": "PURCHASE",
"merchant_name": "KFC65",
"create_time": 1744369075982,
"update_time": 1744369075982,
"related_order_no": "",
"card_present": true,
"country": "CHN",
"city": "Mount Buller2"
"mcc": "7999",
"acquiring_currency": "AUD",
"acquiring_amount": 12.88,
"order_currency": "AUD",
"version": "v1.0",
"tx_direction": "DEBIT"
}

Scenarios

Scenario 1: Successful Purchase (Authorize & Settle)

Scenario 1

Example of webhook

Real-time Authorization

the real-time authorization webhook is as follows:
  {
   "auth_amount": -12.88,
   "auth_currency": "AUD",
   "uid": "1808026787681538048",
   "card_id": "ETLPzgGfSzg-et",
   "create_time": 1744783070549,
   "merchant_name": "UBER",
   "id": "ETLPzgGfSzDTTLQuKEvVlssjq5met",
   "order_no": "1910648503136038912",
   "transaction_type": "PURCHASE",
   "version": "v1.0",
   "acquiring_amount": 12.88,
   "order_currency": "AUD",
   "tx_direction": "DEBIT"
   }

card order webhook

  PENDING state
  {
   "id": "17443690760031910648503412862098",
   "order_no": "1910648503136038912",
   "uid": "1808026787681538048",
   "card_id": "ETLPzgGfSzg-et",
   "order_amount": -12.88,
   "order_status": "PENDING",
   "transaction_type": "PURCHASE",
   "merchant_name": "UBER",
   "create_time": 1744369075982,
   "update_time": 1744369075982,
   "related_order_no": "",
   "card_present": true,
   "country": "CHN",
   "city": "Mount Buller2",
   "mcc": "7999",
   "acquiring_currency": "AUD",
   "acquiring_amount": 12.88,
   "order_currency": "AUD",
   "version": "v1.0",
   "tx_direction": "DEBIT"
  }

  COMPLETED state
 {
  "id": "17443690760031910648503412862678",
  "order_no": "1910648503136038912",
  "uid": "1808026787681538048",
  "card_id": "ETLPzgGfSzg-et",
  "order_amount": -12.88,
  "order_status": "COMPLETED",
  "transaction_type": "PURCHASE",
  "merchant_name": "UBER",
  "create_time": 1744369075982,
  "update_time": 1744369075982,
  "related_order_no": "",
  "card_present": true,
  "country": "CHN",
  "city": "Mount Buller2",
  "mcc": "7999",
  "acquiring_currency": "AUD",
  "acquiring_amount": 12.88,
  "order_currency": "AUD",
  "version": "v1.0",
  "tx_direction": "DEBIT"
 }

Example of transaction simulation

(We are in the process of upgrading the demo trading interface and will be updating the trading demo interface this week.)

This is an example of how to perform this scenario using our payment simulations API in sandbox env:

A Card transaction of 30.11 USD

Authorization

curl --location 'https://testapi.build.app/v1/card/simulate-authorization'
--header 'Authorization: 6IIOSEkPSgxYXFpf2y1gU/phph7nqc9nEJCHJOuZOsIokORxTW5CEGHmSRFAN_XJJZY8gF3wbMEsUoDcPeG8gw=='
--header 'Content-Type: application/json' \

 data '{
   "card_id": "ETLPzgGfSzg_mij", 
   "currency": "USD",
   "amount":30.11,
   "card_acceptor_country_code":"USA",
   "card_acceptor_city":"Santa Monica",
   "country":"CHN",
   "city":"city3",
   "acceptor_name": "MC34",
   "mcc":"5311",
   "transaction_source": "online",
   "card_present":"false", 
   "type": "PURCHASE", 
   "partner_transaction_type": "LOAD" 
 }'

response：

{
  "code": 0,
  "msg": "Success",
  "data": {
    "authorization_id": "ETLPzgGfSzDTTLQuKEvVlssjo.ognh",
    "message": "Success"
  }
}

Settlement

curl --location 'https://testapi.build.app/v1/card/simulate-transaction'
--header 'Authorization: 6IIOSEkPSgxYXFpf2y1gU_pyLe1tqNvjs8hyA2CQmWbDNI3fioBl8CXF_9OuE4WHLf9CEIA6TssOHxPMmTch4Q=='
--header 'Content-Type: application/json' \

 data '{

   "card_id": "ETLPzgGfSzg_mij",
   "acceptor_name": "401 Congress",
   "transaction_source": "online",
   "currency": "USD",
   "amount":30.11,
   "authorization_id": "ETLPzgGfSzDTTLQuKEvVlssjo.ognh",
   "type": "PURCHASE", 
   "partner_transaction_type": "LOAD" 
 }'

response：

{
  "code": 0,
  "msg": "Success",
  "data": {
  "transaction_id": "ETLPzgGfSzWQftUdvTMQqhmgjm-o"
  }
}

Scenario 2: Declined Purchase (by Customer)

This shows the flow when customer system declines the authorization request.

Scenario 2

Example of webhook

Real-time Authorization

  {
   "auth_amount": -129.12,
   "auth_currency": "AUD",
   "uid": "1808026787681538048",
   "card_id": "ETLPzgGfSzg-et",
   "create_time": 1744783070549,
   "merchant_name": "APPLE",
   "id": "ETLPzgGfSzDTTLQuKEvVlssjq6med",
   "order_no": "1910648503136038918",
   "transaction_type": "PURCHASE",
   "version": "v1.0",
   "acquiring_amount": 129.12,
   "acquiring_currency": "AUD",
   "tx_direction": "DEBIT"
   }

card order webhook

  FAILED state
  {
   "id": "17443690760031910648503412862423",
   "order_no": "1910648503136038918",
   "uid": "1808026787681538048",
   "card_id": "ETLPzgGfSzg-et",
   "order_amount": -129.12,
   "order_status": "FAILED",
   "transaction_type": "PURCHASE",
   "merchant_name": "APPLE",
   "create_time": 1744369075982,
   "update_time": 1744369075982,
   "related_order_no": "",
   "card_present": true,
   "country": "CHN",
   "city": "Mount Buller2",
   "mcc":"5122"
   "acquiring_currency": "AUD",
   "acquiring_amount": 129.12,
   "order_currency": "AUD",
   "version": "v1.0",
   "tx_direction": "DEBIT"
  }

Scenario 3: Full Refund/Reversal (Cancels PENDING Order)

This shows a full refund that effectively cancels an existing, unsettled (PENDING) authorization.

Scenario 3

Example of webhook

Real-time Authorization

  {
   "auth_amount": -11.20,
   "auth_currency": "AUD",
   "uid": "1808026787681538048",
   "card_id": "ETLPzgGfSzg-et",
   "create_time": 1744783171547,
   "merchant_name": "STARBUCKS",
   "id": "ETLPzgGfSzDTTLQuKEvVlssjq8mew",
   "order_no": "1828624043283591168",
   "transaction_type": "PURCHASE",
   "version": "v1.0",
   "acquiring_amount": 11.20,
   "acquiring_currency": "AUD",
   "tx_direction": "DEBIT"
   }

card order webhook

  PENDING state

 {
   "id": "17443691760031910648503412862975",
   "order_no": "1828624043283591168",
   "uid": "1808026787681538048",
   "card_id": "ETLPzgGfSzg-et",
   "order_amount": -11.20,
   "order_status": "PENDING",
   "transaction_type": "PURCHASE",
   "merchant_name": "STARBUCKS",
   "create_time": 1744369075982,
   "update_time": 1744369075982,
   "related_order_no": "",
   "card_present": true,
   "country": "CHN",
   "city": "Mount Buller2",
   "mcc":"5122"
   "acquiring_currency": "AUD",
   "acquiring_amount": 11.20,
   "order_currency": "AUD",
   "version": "v1.0",
   "tx_direction": "DEBIT"
  }

  CANCELLED state
  {
   "id": "17443691760031910648503412862569",
   "order_no": "1828624043283591168",
   "uid": "1808026787681538048",
   "card_id": "ETLPzgGfSzg-et",
   "order_amount": -11.20,
   "order_status": "CANCELLED",
   "transaction_type": "PURCHASE",
   "merchant_name": "STARBUCKS",
   "create_time": 1744369075982,
   "update_time": 1744369075982,
   "related_order_no": "",
   "card_present": true,
   "country": "CHN",
   "city": "Mount Buller2",
   "mcc":"5122"
   "acquiring_currency": "AUD",
   "acquiring_amount": 11.20,
   "order_currency": "AUD",
   "version": "v1.0",
   "tx_direction": "DEBIT"
  }

Example of Full Refund simulation

(We are in the process of upgrading the demo trading interface and will be updating the trading demo interface this week.)

This is an example of how to perform this scenario using our simulations API in sandbox env:

Authorization

auth ：

curl --location 'https://testapi.build.app/v1/card/simulate-authorization' --header 'Authorization: 6IIOSEkPSgxYXFpf2y1gU_h7MrHEKS5gi7kE/9WcJrixZgv71kn7l51sPHaGoa0zySRlgj_PzVD6CGBP3ftppg==' --header 'Content-Type: application/json'

data '{
   "card_id": "ETLPzgGfSzg_mij", 
   "currency": "USD",
   "amount":50.11,
   "card_acceptor_country_code":"USA",
   "card_acceptor_city":"Santa Monica",
   "country":"CHN",
   "city":"city3",
   "acceptor_name": "MC34",
   "mcc":"5311",
   "transaction_source": "online",
   "card_present":"false", 
   "type": "PURCHASE", 
   "partner_transaction_type": "LOAD" 
 }'

response：

{
  "code": 0,
  "msg": "Success",
  "data": {
   "authorization_id": "ETLPzgGfSzDTTLQuKEvVlssjo.ogpq",
   "message": "Success"
  }
}

refund

auth-reversal：

curl --location 'https://api.sandbox.build.app/v1/card/simulate-reversal'
--header 'Authorization: GWEkpUqZ1HQUnUkfMEvkRo/odabzeKWiiXhPAs7PIbNUqeEjit6vH5q3_Kzwy4fvwtxY_Y/Px6m251acT2NEBA=='
--header 'Content-Type: application/json' \

the "original_authorization_id" need to be the same as the one in authorization

 data '{
   "card_id": "ETLPzgGfSzg_mij",
   "acceptor_name": "MC34",
   "transaction_source": "online",
   "original_authorization_id": "ETLPzgGfSzDTTLQuKEvVlssjo.ogpq",
   "partial": 0,
   "amount": 50.11
 }'

response：

{
  "code": 0,
  "msg": "Success",
  "data": {
  "id": "ETLPzgGfSzDTTLQuKEvVlssjqo-e"
  }

}

Example of webhook

Scenario 4: Partial Refund (Creates New PENDING Order)

This shows a refund (partial or after settlement) that creates a new credit order.

Scenario 4

Initial Purchase: The flow starts with a standard purchase authorization, resulting in a PENDING debit order ('123').
Partial Refund Auth: The subsequent partial refund is processed as a separate credit authorization.
New Order Creation: Build recognizes this is not a full reversal of the original transaction amount. Therefore, it creates a new credit order ('456') instead of cancelling the original one.
Two Completed Orders: the credit order ('456') may bypass the PENDING state and transition directly to COMPLETED after the associated debit order ('123') is settled and transition to COMPLETED.

Real-time Authorization (Makes Purchase (e.g., $100))

{
   "auth_amount": -100.00,
   "auth_currency": "USD",
   "uid": "1808026787681538048",
   "card_id": "ETLPzgGfSzg-et",
   "create_time": 1744783171547,
   "merchant_name": "STARBUCKS",
   "id": "ETLPzgGfSzDTTLQuKEvVlssjq1jrt",
   "order_no": "1828624143283598812",
   "transaction_type": "PURCHASE",
   "version": "v1.0",
   "acquiring_amount": 100,
   "acquiring_currency": "USD",
   "tx_direction": "DEBIT"
}

card order webhook （purchase order）

PENDING state
{
   "id": "17443691760031910648503412809126",
   "order_no": "1828624143283598812",
   "uid": "1808026787681538048",
   "card_id": "ETLPzgGfSzg-et",
   "order_amount": -100.00,
   "order_status": "PENDING",
   "transaction_type": "PURCHASE",
   "merchant_name": "STARBUCKS",
   "create_time": 1744369075982,
   "update_time": 1744369075982,
   "related_order_no": "",
   "card_present": true,
   "country": "US",
   "city": "Mount Buller2",
   "mcc":"5122",
   "acquiring_currency": "USD",
   "acquiring_amount":100.00,
   "order_currency": "USD",
   "version": "v1.0",
   "tx_direction": "DEBIT"
}

Real-time Authorization (The cardholder initiated a partial refund of $30)

{
   "auth_amount": 30.00,
   "auth_currency": "USD",
   "uid": "1808026787681538048",
   "card_id": "ETLPzgGfSzg-et",
   "create_time": 1744783174518,
   "merchant_name": "STARBUCKS",
   "id": "ETLPzgGfSzDTTLQuKEvVlssjq4trp",
   "order_no": "1828624143283598812",
   "transaction_type": "REFUND",
   "version": "v1.0",
   "acquiring_amount": 30,
   "acquiring_currency": "USD",
   "tx_direction": "CREDIT"
}

card order webhook(purchase order)

COMPLETED state
{
   "id": "17443691760031910648503412809126",
   "order_no": "1828624143283598812",
   "uid": "1808026787681538048",
   "card_id": "ETLPzgGfSzg-et",
   "order_amount": -100.00,
   "order_status": "COMPLETED",
   "transaction_type": "PURCHASE",
   "merchant_name": "STARBUCKS",
   "create_time": 1744369075982,
   "update_time": 1744369075982,
   "related_order_no": "",
   "card_present": true,
   "country": "US",
   "city": "Mount Buller2",
   "mcc":"5122",
   "acquiring_currency": "USD",
   "acquiring_amount":100.00,
   "order_currency": "USD",
   "version": "v1.0",
   "tx_direction": "DEBIT"
}

card order webhook(refund order)

COMPLETED state
{
   "id": "17443691760031910648503412809876",
   "order_no": "1828624143283596623",
   "uid": "1808026787681538048",
   "card_id": "ETLPzgGfSzg-et",
   "order_amount": 30.00,
   "order_status": "COMPLETED",
   "transaction_type": "REFUND",
   "merchant_name": "STARBUCKS",
   "create_time": 1744369075982,
   "update_time": 1744369075982,
   "related_order_no": "1828624143283598812",
   "card_present": true,
   "country": "CHN",
   "city": "Mount Buller2",
   "mcc":"5122",
   "acquiring_currency": "USD",
   "acquiring_amount": 30.00,
   "order_currency": "USD",
   "version": "v1.0",
   "tx_direction": "CREDIT"
}

Example of Partial Refund simulation

(We are in the process of upgrading the demo trading interface and will be updating the trading demo interface this week.)

this is an example of how to perform this scenario using our simulations API in sandbox env, please notice that the order status transition in simulation of this scenario may require support of Build team:

Authorization

auth ：

data '{
   "card_id": "ETLPzgGfSzg_mij", 
   "currency": "USD",
   "amount":50.11,
   "card_acceptor_country_code":"USA",
   "card_acceptor_city":"Santa Monica",
   "country":"CHN",
   "city":"city3",
   "acceptor_name": "MC34",
   "mcc":"5311",
   "transaction_source": "online",
   "card_present":"false", 
   "type": "PURCHASE", 
   "partner_transaction_type": "LOAD" 
 }'

response：

{
  "code": 0,
  "msg": "Success",
  "data": {
   "authorization_id": "ETLPzgGfSzDTTLQuKEvVlssjo.ogpq",
   "message": "Success"
  }
}

refund

auth-reversal：

 data '{
   "card_id": "ETLPzgGfSzg_mij",
   "acceptor_name": "MC34",
   "transaction_source": "online",
   "original_authorization_id": "ETLPzgGfSzDTTLQuKEvVlssjo.ogpq",
   "partial": 0,
   "amount": 40.00
 }'

response：

{
  "code": 0,
  "msg": "Success",
  "data": {
   "id": "ETLPzgGfSzDTTLQuKEvVlssjqo-e"
  }
}

In Reversal simulation, original_authorization_id is not required.

Scenario 5: Authorization Expiration

This shows what happens when a PENDING authorization is not captured/settled within the allowed timeframe.

Scenario 5

Example of webhook

Real-time Authorization

  {
   "auth_amount": -10.20,
   "auth_currency": "AUD",
   "uid": "1808026787681538048",
   "card_id": "ETLPzgGfSzg-et",
   "create_time": 1744783171522,
   "merchant_name": "STARBUCKS",
   "id": "ETLPzgGfSzDTTLQuKEvVlssjq9jjq",
   "order_no": "1828624143283596648",
   "transaction_type": "PURCHASE",
   "version": "v1.0",
   "acquiring_amount": 10.20,
   "acquiring_currency": "AUD",
   "tx_direction": "DEBIT"
   }

card order webhook

  PENDING state

 {
   "id": "17443691760031910648503412812347",
   "order_no": "1828624143283596648",
   "uid": "1808026787681538048",
   "card_id": "ETLPzgGfSzg-et",
   "order_amount": -10.20,
   "order_status": "PENDING",
   "transaction_type": "PURCHASE",
   "merchant_name": "STARBUCKS",
   "create_time": 1744369075982,
   "update_time": 1744369075982,
   "related_order_no": "",
   "card_present": true,
   "country": "CHN",
   "city": "Mount Buller2",
   "mcc":"5122",
   "acquiring_currency": "AUD",
   "acquiring_amount": 10.20,
   "order_currency": "AUD",
   "version": "v1.0",
   "tx_direction": "DEBIT"
  }

  CANCELLED state

 {
   "id": "17443691760031910648503412812890",
   "order_no": "1828624143283596648",
   "uid": "1808026787681538048",
   "card_id": "ETLPzgGfSzg-et",
   "order_amount": -10.20,
   "order_status": "CANCELLED",
   "transaction_type": "PURCHASE",
   "merchant_name": "STARBUCKS",
   "create_time": 1744369075982,
   "update_time": 1744369075982,
   "related_order_no": "",
   "card_present": true,
   "country": "CHN",
   "city": "Mount Buller2",
   "mcc":"5122",
   "acquiring_currency": "AUD",
   "acquiring_amount": 10.20,
   "order_currency": "AUD",
   "version": "v1.0",
   "tx_direction": "DEBIT"
  }

Simulation

In sandbox env, to simulate this scenario:

make a pass authorization, and don't call any reversal/settlement API.
the auth will be expired after 5min.

in prod env, this may take up to T+14 days.

Scenario 6: Settlement Without Prior Authorization (Rare)

This covers the edge case where a transaction appears directly in settlement.

Scenario 6

card order webhook

  COMPLETED state

 {
   "id": "1744369176003191064850341280876",
   "order_no": "1828624143283596615",
   "uid": "1808026787681538048",
   "card_id": "ETLPzgGfSzg-et",
   "order_amount": -10.20,
   "order_status": "COMPLETED",
   "transaction_type": "PURCHASE",
   "merchant_name": "STARBUCKS",
   "create_time": 1744369075982,
   "update_time": 1744369075982,
   "related_order_no": "",
   "card_present": true,
   "country": "CHN",
   "city": "Mount Buller2",
   "mcc":"5122",
   "acquiring_currency": "AUD",
   "acquiring_amount": 10.20,
   "order_currency": "AUD",
   "version": "v1.0",
   "tx_direction": "DEBIT"
   
  }

Notice

We are in the process of upgrading the demo trading interface and will be updating the trading demo interface this week.