Callback URL with IPN

Callback mechanism is a back-end activity that is initiated by payment gateway to notify the merchant system once there are changes on any payment status.

Callback URL script is similar to return URL script. Both handle the payment status result; Unlike the return URL script, callback URL script is to handle defer status update or all other non-realtime payment status updates, such as Permata VA channel.

Merchant must fill the Callback URL in merchant admin in order to get those non-realtime status update from the gateway. Callback URL IPN can be activated for better merchant-payment system communication. Instead of returning all parameters from the gateway, merchant’s callback script just need to echo “CBTOKEN:MPSTATOK”, in plaintext, without double quotes or any HTML tags.

Merchant can actually use the same script for both callback URL & return URL, because there is only one extra parameter in callback request, in addition to return URL parameters, which is “nbcb”. Besides, an additional status code, 22 has been introduced for “pending” transaction status.

Once there is a status changed event, payment gateway will POST the following parameters to mechant callback URL. If the payment gateway could not get the actual ACK message from the merchant, it will retry for a maximum 3 times, of 15 minutes interval for each attempt.

Callback Parameters (via POST method)

Variable / Parameter	Type Format / Max Length	Description / Example
nbcb	1 digit numeric	Always equal to 1, which indicates this is a callback notification from PG
amount	2 decimal points numeric value	The total amount paid or to be paid for Permata VA payment request
orderid	alphanumeric, 32 characters	Invoice or order number from merchant system.
tranID	integer, 10 digits	Unique transaction ID for tracking purpose
domain	alphanumeric, 32 chars	Merchant ID in PG system
status	2-digit numeric value	00 for Successful payment 11 for failed status
appcode	alphanumeric, 16 chars	Bank approval code. Mandatory for card payment. Certain channel returns empty value
error_code	alphanumeric	Refer to the Error Codes section
error_desc	text	Error message or description
skey	32 chars hexadecimal string	This is the data integrity protection hash string. Refer skey section for details
currency	2 or 3 chars (ISO-4217) currency code	Default currency is IDR(indicating Indonesia Rupiah) for Indonesia channels
channel	predefined string in system	Channel references for merchant system
paydate	Date/Time( YYYY-MM-DD HH:mm:ss)	Date/Time of the transaction
extraP*	optional (on request) - for credit channel	JSON encoded string or array token: 16-digit card token or Direct Debit token for merchant to store for recurring MIT (merchant initiated transaction) fraudscreen: 1-digit integer, i.e. 1=Unknown, 2=Passed, 3=Alert, 4=Suspicious, 5=Fraud fpx_txn_id: FPX transaction ID fpx_buyer_name: FPX buyer name ccbrand: Visa, MasterCard, AMEX cclast4: Last 4-digit of card number cctype: Credit, Debit, Prepaid captured_date: Date/Time of the transaction status updated from authorized to captured

*Note: Values are not URL encoded

Example of callback URL script for PHP

<?php

$sec_key ="xxxxxxxxxx"; //Replace xxxxxxxxxx with Secret_Key

$nbcb 	        =	$_POST['nbcb'];
$tranID 	=	$_POST['tranID'];
$orderid 	=	$_POST['orderid'];
$status 	=	$_POST['status'];
$domain 	=	$_POST['domain'];
$amount 	=	$_POST['amount'];
$currency 	=	$_POST['currency'];
$appcode 	=	$_POST['appcode'];
$paydate 	=	$_POST['paydate'];
$skey 	        =	$_POST['skey'];

/***********************************************************
* To verify the data integrity sending by PG
************************************************************/
$key0 = md5( $tranID.$orderid.$status.$domain.$amount.$currency );
$key1 = md5( $paydate.$domain.$key0.$appcode.$sec_key );
if( $skey != $key1 ) $status= -1; // Invalid transaction

if ( $status == "00" ) {
  if ( check_cart_amt($orderid, $amount) ) {
    // write your script here .....
  }
} else {
  // failure action
  // write your script here .....
}

if ( $nbcb==1 ) {
  //callback IPN feedback to notified PG
  echo “CBTOKEN:MPSTATOK”; exit;
}else{
  //normal IPN and redirection
}
?>

Value of "Channel" in notification and callback URL

Card / Wallet

Country	Value of request & response	Display Name
Indonesia	CIMB_NIAGA	Visa/Mastercard/JCB

Indirect / Direct Internet Banking

Channel	Value of request & response	Display Name
CIMB OctoClicks	E2PAY_CIMBOCTOCLICKS_IB	e2Pay CIMBOctoClicks IB
DBank Pro	E2PAY_DBANKPRO_IB	e2Pay DBankPro IB

e-Wallets

Channel	Value of request & response	Display Name
CIMB QRIS	E2PAY_CIMB_QRIS	e2Pay CIMB QRIS
CIMB OctoPay	E2PAY_CIMB_OCTOPAY	e2Pay CIMB Rekening Ponsel
DANA	E2PAY_DANA	e2Pay DANA
LinkAja Applink	E2PAY_LINKAJA_APPLINK	e2Pay LinkAja Applink
LinkAja QRIS	E2PAY_LINKAJA_QRIS	e2Pay LinkAja QRIS
LinkAja Web Checkout	E2PAY_LINKAJA_WCO	e2Pay LinkAja Web Checkout
OVO	E2PAY_OVO	e2Pay OVO
ShopeePay JumpApp	E2PAY_SHOPEEPAY_JUMPAPP	e2Pay ShopeePay JumpApp
ShopeePay QRIS	E2PAY_SHOPEEPAY_QRIS	e2Pay ShopeePay QRIS
GOPAY	E2PAY_GOPAY	e2Pay GOPAY
MBayar QR	E2PAY_MBAYAR_QR	e2Pay MBayar QR

Kiosk / Over-the-Counter / Cash / Bill Payment

Channel	Value of request & response	Display Name
BNI Virtual Account	E2PAY_BNI_VA	e2Pay BNI Virtual Account (VA)
CIMB Virtual Account	E2PAY_CIMB_VA	e2Pay CIMB Virtual Account (VA)
Mandiri Virtual Account	E2PAY_MANDIRI_VA	e2Pay Mandiri Virtual Account (VA)
Permata Virtual Account	E2PAY_PERMATA_VA	e2Pay Permata Virtual Account (VA)
BCA Virtual Account	E2PAY_BCA_VA	e2Pay BCA Virtual Account (VA)
BRI Virtual Account	E2PAY_BRI_VA	e2Pay BRI Virtual Account (VA)
Alfamart	E2PAY_ALFAMART	e2Pay Alfamart
Indomaret	E2PAY_INDOMARET	e2Pay Indomaret

Buy Now Pay Later

Channel	Value of request & response	Display Name
Kredivo	E2PAY_KREDIVO_FN	e2Pay Kredivo Financing
Indodana	E2PAY_INDODANA_FN	e2Pay Indodana