Card callbacks and notifications

Card 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:PUT

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

consumes:*/*

Note:

Status:

code	description	schema
199	OK	BuildCallbackResp

Request payload:

{
  "type": "refund",
  "billing_amount": 100,
  "acceptor_name": "acceptorName#1",
  "transaction_source": "online",
  "card_id": "ETLPzgGfSzgoe",
  "id": "ETLPzgGfSzDTTLQuKEvVlssjj.",
  "reversal": 0,
  "created_at": 0,
  "updated_at": 0
}

Response Params:

name	description	type	schema
responseCode	response code,0 for success ,other none-zero values indicate failure	integer(int32)	integer(int32)
message		string
externalReference		string

Response Example:

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

Reversals

When Build receives a Reversal message for a card, a call will be made to this Reversal API to process the request.

url:Callback url for reversals on your end

method:PUT

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

consumes:*/*

Note:

Status:

code	description	schema
200	OK	BuildCallbackResp

Response Params:

name	description	type	schema
responseCode	response code,0 for success ,other none-zero values indicate failure	integer(int32)	integer(int32)
message		string
externalReference		string

Request payload for Reversal:

{
  "id": "ETLPzgGfSzWQftUdvTMQqhqfr",
  "type": "PURCHASE",
  "callback_type": "REVERSAL",
  "reversal_type": "AUTHORIZATION",
  "fee_amount": 77.7,
  "billing_currency": "AUD",
  "billing_amount": 77.70,
  "acquirer_currency": "AUD",
  "acquirer_amount": 77.70,
  "compliance_currency": "AUD",
  "compliance_amount": -77.70,
  "acceptor_name": "401 Congress",
  "transaction_source": "Online",
  "partner_transaction_type": "load",
  "card_id": "ETLPzgGfSzg5oq",
  "authorization_id": "ETLPzgGfSzDTTLQuKEvVlssjo9-",
  "auth_code": "815163",
  "acquiring_institution_id": "123456",
  "card_present": "false",
  "card_acceptor_country_code": "AU",
  "card_acceptor_city": "Austin",
  "mcc": "1234",
  "pos_entry_mode": "02",
  "pos_condition": "00001",
  "reversal": 1,
  "createdAt": 0,
  "updatedAt": 0
}

Please note: If the reversal_type is AUTHORIZATION, it indicates a reversal of an authorization. In this case, you should take actions to unfreeze the related funds. If the reversal_type is TRANSACTION, it signifies a reversal of a transaction. In such instances, you should take actions to adjust the balance of your user accordingly.

Transactions

When Build receives a Clearing message for a card, a call will be made to this Transactions API to process the request.

url:Callback url for transactions on your end

method:PUT

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

consumes:*/*

Note:

Status:

code	description	schema
200	OK	BuildCallbackResp

Response Params:

name	description	type	schema
responseCode	response code,0 for success ,other values indicate failure	integer(int32)	integer(int32)
message		string
externalReference		string

Request payload for Purchase:

{
  "id": "ETLPzgGfSzWQftUdvTMQqhphh",
  "type": "purchase",
  "callback_type": "transaction",
  "fee_amount": 0.0,
  "billing_amount": 0,
  "acquirer_currency": "AUD",
  "acquirer_amount": 100.00,
  "compliance_currency": "AUD",
  "compliance_amount": -100.00,
  "acceptor_name": "",
  "transaction_source": "Online",
  "partner_transaction_type": "load",
  "card_id": "ETLPzgGfSzg5oq",
  "auth_code": "256434",
  "acquiring_institution_id": "00000000000",
  "card_present": "false",
  "mcc": "0000",
  "pos_entry_mode": "D10100C910",
  "pos_condition": "0000",
  "reversal": 0,
  "createdAt": 0,
  "updatedAt": 0
}

Request payload for Refund:

{
  "id": "ETLPzgGfSzWQftUdvTMQqhphj",
  "type": "refund",
  "callback_type": "transaction",
  "fee_amount": 0.0,
  "billing_amount": 0,
  "acquirer_currency": "AUD",
  "acquirer_amount": 111.00,
  "compliance_currency": "AUD",
  "compliance_amount": 111.00,
  "acceptor_name": "",
  "transaction_source": "Online",
  "partner_transaction_type": "withdraw",
  "card_id": "ETLPzgGfSzg5oq",
  "auth_code": "256434",
  "acquiring_institution_id": "00000000000",
  "card_present": "false",
  "mcc": "0000",
  "pos_entry_mode": "D10100C910",
  "pos_condition": "0000",
  "reversal": 0,
  "createdAt": 0,
  "updatedAt": 0
}

Response Example:

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

Business instructions on transactions

If the card transaction results in a debit (for example, a purchase or withdrawal) from a customer account, the partnerTransactionType is a load. Your system debits funds from the customer account in your system.
If the card transaction results in a credit (for example, a refund or chargeback) to a customer account, the partnerTransactionType is a withdraw. Your system debits funds to the customer account in your system.
If the transaction is a reversal (reversal=1 and callbackType="reversal"), then previous authorization("authorization_id" is the relevant authorization) is reversed.

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": "CardApplicationStateEvent",
  "application_id": "ETLPzgGfSzDtuPNfeTMQqhmnq",
  "status": "SUBMITTED",
  "timestamp": 1690360293489
}

CardStateEvent

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

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