CardOrder callbacks and notifications

Cardorder callbacks helps our clients to do card bussiness. Once our customer returns a decision, Build finalizes the response back to the card network, generates the ISO 8583 message, and returns the ISO 8583 message back to the card network to complete the card payment process.

Prerequisites

To use callbacks and notifications with Build as the issuer processor, Build must enable HTTP connections with your system. Customers are required to provide these API callback URLs.

Authorizations

When Build receives an authorization message for a card, a call will be made to this Authorization API to process the request. Build's customer should decide whether to do this authorization and response the answer in the request body.

url:{authorization callback url on your end}

method:POST

produces:application/x-www-form-urlencoded,application/json

consumes:*/*

Note:

Status:

Request payload:

{
  "auth_amount": 128.88,
  "currency": "AUD",
  "uid": "1808026787681538048",
  "card_id": "ETLPzgGfSzg-ef",
  "tran_time": 1724783070549,
  "merchant_name": "PELICANA.",
  "id": "ETLPzgGfSzDTTLQuKEvVlssjq5mer",
  "order_no": "1828633042242514944",
  "transaction_type": "PURCHASE",
  "auth_type": "AUTH"
}

Please note: If the auth_amount is positive, it means crediting the user's account. If the amount is negative, it means debiting the user's account

Response Params:

Response Example:

{
	"response_code": 0,
	"message": "success",
	"external_reference": ""
}

Card Order

When Build create a card order or the field related to a card order have changed, Build will send card order notification

url:Callback url for CardOrder on your end

method:POST

produces:application/x-www-form-urlencoded,application/json

consumes:*/*

Note:

Status:

Response Params:

Request payload for cardorder:

{
  "id": "17295916968821828633042242514988",
  "order_no": "1828633042242514944",
  "uid": "1703683603805798401",
  "card_id": "ETLPzgGfSzg-gp",
  "currency": "AUD",
  "order_amount": 77.70,
  "settle_amount": 71.70,
  "reversal_amount": 6.00,
  "order_status": "PENDING",
  "transaction_type": "PURCHASE",
  "merchant_name": "COSTCO MARSDEN PARK",
  "create_time": 1725852671294,
  "update_time": 1725851396769,
  "order_type": "Standard Order",
  "transaction_amount": 12.00,
  "transaction_currency": "AUD",
  "card_present": true,
  "country": "AUS",
  "city": "Perth",
  "mcc": "8756",
  "related_order_no": "1839607950353510400,1839607408550096896"
}

Please note: If the order_amount is positive, it means crediting the user's account. If the amount is negative, it means debiting the user's account

Appendix

Order Type

Standard Order

Standard Order generated by card transactions

Manual Reconcile

Manually Reconcile order, usually added in cases where the settlement amount and the authorized amount are inconsistent. It will be associated with the original order

Manual Adjustment

Manually Adjustment order, usually created for user account adjustments and does not need to be associated with existing orders

Order Status

PENDING

When an order is created, its initial status is PENDING

WAITING FOR REVIEW

Indicates that an order is in a state of manual review

COMPLETED

Indicates that an order has been completed

CANCELLED

Indicates that an order has been cancelled

FAILED

Indicates that an order has been failed

Transaction Type

REFUND PURCHASE

Please note: whenever a card order is created or the order amount, settle amount, or reversal amount changes, or when the order status changes, the system will send a notification message. Each time, the full message will be pushed to downstream recipients.

Notifications

Build supports several types of system-generated notifications, which are similar to trigger alerts that are sent in response to a specific user action or event. Each notification contains an event type and some other relevant fields.

url:Callback url for notifications on your end

method:POST

produces:application/x-www-form-urlencoded,application/json

Event Types

• CardApplicationStateEvent

When card applications' states change, this kind of notification will be sent. Request body example:

{
  "event_type": "CARD_APPLICATION_STATE_EVENT",
  "application_id": "ETLPzgGfSzDtuPNfeTMQqhmnq",
  "status": "SUBMITTED",
  "timestamp": 1690360293489
}

• CardStateEvent

When cards' states change, this kind of notification will be sent. Request body example:

{
  "event_type": "CARD_STATE_EVENT",
  "card_id": "ETLPzgGfSzg5mq",
  "application_id": "ETLPzgGfSzDtuPNfeTMQqhmnq",
  "status": "NEW",
  "timestamp": 1690360288486
}

• ActivationCodeEvent

When card is bind(or unbind) to the e-wallet, this kind of notification will be sent. Request body example:

{
  "event_type":"ACTIVATION_CODE_EVENT",
  "activation_code":"624582",
  "activation_method":"SMS",
  "card_id":"ETLPzgGfSzg.mir",
  "expiration_time":1736491830000
}

please notice that  activation_method can be SMS or EMAIL