NFC Pre-Authorization API v1.
04
Pre-Authorization
URL
Provides processing of pre-authorization message. The pre-
authorization message is used when the merchant originating
transactions does not know the exact amount that should be charged
to fulfill the goods or services. GCash will deduct the amount from
customers account and will temporarily hold that amount. All pre-
LAB Environment:
authorized approved transactions will be active for 30 days and POST https://nfc.lab.mynt.xyz
merchant may clear the pre-authorized amount in single clearing or /nfc/v5/pre-auth/approval
multiple clearing.
POST https://nfc.lab.mynt.xyz
See: NFC: API Authentication Instruction
/nfc/v5/webhook/notification
SIT Environment:
(to follow)
Endpoints
POST /nfc/v5/pre-auth/approval
POST /nfc/v5/webhook
/notification
The Pre-Authorization Approval Object
The Pre-Authorization Approval Object
Attributes
tenant_reference_id STRING REQUIRED
{
Tenant transaction ID "tenant_reference_id":
approved_amount NUMBER REQUIRED
"31XXXX6723173606",
"approved_amount": 0.0,
Amount in base currency unit. Set to 0, when declined. Approved
amount must be the same as transaction amount, when approved.
"status": "declined",
"reason": "Insufficient
status STRING REQUIRED balance"
If Tenant approve the Transaction set to “approved” else “declined” }
reason STRING REQUIRED
Can set null or empty strings when approved. (Required) non
empty strings when declined
Pre-Authorization Approval
Request
Process pre-authorization message and move funds from customer
to holding wallet. The pre-authorized amount will be on hold until the
merchant clears the approved pre-authorized transactions, this will
ensure that the funds will not be used for final-authorization and pre-
authorization approvals.
POST /nfc/v5/pre-auth/approval
Parameters {
"transaction_id": "6182bde8-
transaction_id UUID REQUIRED
ee3e-4bd5-935e-e56507e0f809",
"network_transaction_ref":
Middleware transaction ID
"awqcB1rPDuJIm4yKOQbqJUj5Mvpdc
network_transaction_ref STRING REQUIRED H6E",
"customer_id": "8e64c3c2-
Mastercard Transaction LifeCycle ID
f409-4e0b-afb7-05cce88d26d7",
customer_id UUID REQUIRED "tenant_customer_ref":
Middleware Customer ID "01HG04B4NDBB7XT9JY6H1Y2B3A",
"device_id": "f4e52b39-3664-
tenant_customer_ref STRING REQUIRED 48ce-844c-7a92772b1f2e",
Tenant Customer ID "network_message_ref":
"CZLIzgNfeyMCabcsXp3liJPgSVGyQ
device_id UUID REQUIRED
ypHI2B",
Middleware PbA Account Device ID. "network_merchant_name":
network_message_ref STRING REQUIRED
"Merchant123456",
"network_merchant_id":
Mastercard Zapp Message ID
"6000123456",
network_merchant_id STRING REQUIRED
"network_merchant_outlet_addre
Mastercard merchant ID.
ss": "Central, Singapore",
network_merchant_name STRING REQUIRED
Merchant name from Mastercard. "network_merchant_category_cod
e": "1234",
network_merchant_outlet_address STRING REQUIRED "auth_indicator": {
Merchant outlet address from Mastercard
"is_incremental_approval":
network_merchant_category_code STRING REQUIRED
false,
The category code of the Merchant according to Mastercard
auth_indicator OBJECT REQUIRED
"is_undefined_authorization":
true
Indicate if the authorization approval is incremental or undefined
},
Show child attribute
"amount": 200.00,
is_incremental_approval BOOLEAN OPTIONAL
"currency": "SGD",
True will indicate this is an additional approval on an existing "billing_amount": 200.00,
transaction to increase the authorization amount
"billing_currency_code":
is_undefined_authorization(TBC) BOOLEAN "SGD",
OPTIONAL "billing_exchange_rate":
True will indicate this is an Undefined-Authorization. The 1.00,
amount appearing in EOC and EOS files for this transaction "settlement_amount": 200.00,
may be different from the authorization amount. And the
expiration duration will be 7 days instead of 30 days. "settlement_currency_code":
"SGD",
amount NUMBER REQUIRED "settlement_exchange_rate":
1.00,
Transaction amount in base currency unit
"txn_source": "terminal",
currency STRING REQUIRED "txn_category":
Transaction currency in ISO 4217 format
"cardholder_activated_terminal
"
}
Response
billing_amount NUMBER REQUIRED
Billing amount in base currency unit APPROVED
[Q: What is the difference between the amount, billing amount,
and settlement amount?]
[A:] "amount" is transaction amount in the "currency" of merchant
{
when they charge the customer. "billing_amount" is the same "response": {
amount converted to "billing_currency_code" using "body" : {
"billing_exchange_rate" this currency will be PHP for Gcash.
similar for "settlement_amount", "settlement_currency_code" will "tenant_reference_id":
be agreed between Gcash and Mastercard (if choose PHP "31XXXX6723173606",
settlement amount will not be present as it will be same as billing
amount)
"approved_amount":
200.0,
billing_currency_code STRING REQUIRED "status": "approved",
Billing currency of Tenant in ISO 4217 format "reason": null
}
billing_exchange_rate NUMBER REQUIRED
},
Exchange rate when calculate billing amount in base currency unit "version": "1"
settlement_amount NUMBER REQUIRED
}
Settlement amount in base currency unit
settlement_currency_code STRING REQUIRED DECLINE
Settlement currency in ISO 4217 format
settlement_exchange_rate NUMBER REQUIRED
{
calculate settlement amount in base currency unit "response": {
txn_source STRING REQUIRED
"body" : {
"tenant_reference_id":
source where the transaction originated. “terminal” / “ecommerce” "31XXXX6723173606",
txn_category STRING REQUIRED "approved_amount": 0.0,
"status": "declined",
category of the transaction determined by Open Fabric. Common
transactions will be “other”. For special use cases such as: "reason": "Insufficient
Transit. This will be “transit” balance"
}
Return },
"version": "1"
Returns the Approval object after successful pre-authorization
request. The return can be decline or approve. }
Pre-Authorization Reversal
Request
After the approval of pre-authorization request and hold the
transaction amount, the merchant can send a pre-authorization
reversal request and move back the transaction amount to customer’
s balance.
Parameters
notification_id UUID REQUIRED
Middleware notification ID
type STRING REQUIRED
POST /nfc/v5/webhook
Possible values: “v1:pba:transaction:pre_auth_reversed” or /notification
”v1:pba:transaction:final_auth_reversed”
{
created_at STRING REQUIRED "notification_id":
Notification creation timestamp, in ISO 8601 Date Time format.
"8bedf365-8442-4b6e-a480-
7dad7b40ac44",
data OBJECT REQUIRED "type": "v1:pba:
Refer to Notification Payload Data below transaction:
pre_auth_reversed",
Notification Payload Data
"created_at": "2023-06-
notification_id UUID REQUIRED 24T14:15:22Z",
Middleware notification ID
"data": {
"notification_id":
transaction_id UUID REQUIRED "8bedf365-8442-4b6e-a480-
Middleware transaction ID 7dad7b40ac44",
"transaction_id":
tenant_reference_id STRING REQUIRED
"6182bde8-ee3e-4bd5-935e-
GCash transaction ID e56507e0f810",
network_transaction_ref STRING REQUIRED
"tenant_reference_id":
Mastercard Transaction LifeCycle ID "31XXXX6723173607",
network_message_ref STRING REQUIRED
"network_transaction_ref":
Mastercard Unique ID for this message
"awqcB1rPDuJIm4yKOQbqJUj5Mvpdc
amount NUMBER REQUIRED H6E",
Transaction amount in base currency unit
"network_message_ref":
currency STRING REQUIRED "CZLIzgNfeyMCabcsXp3liJPgSVGyQ
Transaction currency in ISO 4217 format ypHI2C",
"amount": 50.00,
billing_amount NUMBER REQUIRED
"currency": "SGD",
Billing amount in base currency unit "billing_amount":
50.00,
billing_currency_code STRING REQUIRED
Billing currency of Tenant in ISO 4217 format "billing_currency_code":
billing_exchange_rate NUMBER REQUIRED "SGD",
Exchange rate when calculate billing amount in base currency unit
"billing_exchange_rate": 1.00,
settlement_amount NUMBER REQUIRED "settlement_amount":
Settlement amount in base currency unit
50.00,
settlement_currency_code STRING REQUIRED "settlement_currency_code":
Settlement currency in ISO 4217 format "SGD",
settlement_exchange_rate NUMBER REQUIRED
"settlement_exchange_rate":
calculate settlement amount in base currency unit 1.00
}
Return }
Returns .
Response
HTTP 200
{
"response": {
"body": {
"message": "Notification
received."
}
},
"version": "1"
}
