Brankas Direct API v1.0.0

Brankas Direct provides Fintechs, Corporates and SMEs with an API-driven payment solution that allows to digitally transact with customers and their end-users. By debiting the customers' online bank accounts and transferring directly to the fintech’s or SME’s payable accounts, Brankas Direct leverages on enterprises that are able to execute fund transfer-based transactions over a growing basket of banks via a single set of APIs.

  • Host https://direct.sandbox.bnk.to

API Reference Overview

Checkout

The Checkout endpoint creates a fund transfer initiation request that the end user can complete via the Brankas Tap. The Checkout endpoint is a fund transfer initiation request specific to the use case where the transaction amount is a predetermined value not defined by the end user, usually determined by an invoice or cart. Direct will create a unique user session on the Brankas Tap keyed to the fund transfer request’s internal transfer_id. The Checkout endpoint will respond with a preformatted URL that the end user must be redirected to in order to authorize the current fund transfer request. The Brankas Client needs to append the returned preformatted URL with their own redirect_uri query parameter where the end user will be sent after they have completed their session on the Brankas Tap.

curl -X POST \
	https://direct.sandbox.bnk.to/v1/checkout \
	-H 'x-api-key: USE_YOUR_API_KEY' \
	-d '{
		"customer": {
			"fname": "John",
			"lname": "Johnson",
			"mname": "Joseph",
			"customer_id": "4f30b317-f98b-4454-bc05-7c4a2e48ec0d",
			"email": "john.johnson@domain.com",
			"mobile": "+62-283-5559-907"
		},
		"reference_id": "9005376336",
		"amount": {
			"cur": "IDR",
			"num": "10000"
		},
		"from": {
			"type": "BANK",
			"bank_code": "BCA_PERSONAL",
			"country": "ID"
		},
		"payment_channel": "_",
		"memo": "A note attached to the transaction",
		"destination_account_id": "b3f1a14c-c0dd-11ea-8f93-ca56f9871a24",
		"client": {
			"display_name": "Your Application Name",
			"logo_url": "https://example.com/logo.svg",
			"return_url": "https://example.com/success",
			"fail_url": "https://example.com/error"
		},
		"expiry_date_time": "2021-07-30T00:00:00Z",
		"unique_amount": "UniqueAmountType"
	}'

HTTP Request

POST https://direct.sandbox.bnk.to/v1/checkout

Body Parameters

Name Type Description
customer Customer customer is the end user’s identifying and contact information that allows transactions to be attributed to a specific end user. This can be used by both banks and settlement channels to assist in the resolution of transaction disputes.
reference_id string reference_id is an additional identifier, such as a UUID, that corresponds to an invoice, cart, or transaction object. The Brankas Client can use this field to associate the fund transfer request to a corresponding transaction object in its transaction database.
amount Amount amount is the transaction amount to be transferred from the source account to the destination account. If minor currency units are supported by a currency, then they are stored as minor units. For example, PHP 100.00 would be represented as “amount.num”: “10000”. Note that amounts are stored as string instead of integers in order to prevent any errors caused by floating point numbers.
from AccountInfo from is the source account information. Bank code parameter is optional. If bank code is set in checkout request, then Brankas Tap would show the bank selector page. If it is not set, then Brankas Tap would not show the bank selector page. Bank Codes used in this field follow a different convention from the bank codes used for the destination account in the to object. For the full list of supported bank codes, see Source Account Bank Codes in the Bank Codes section.
payment_channel PaymentChannelType payment_channel is to be used when initiating a transaction using a settlement partner. For normal fund transfer, this parameter is optional.
memo string memo is a merchant defined remarks attached to the transfer in the memo line (e.g. RRN).
destination_account_id string destination_account_id is the string ID corresponding to the bank information of the recipient. To get your destination_account_id, register the destination account in Brankas Dashboard > Settings > Direct tab
client Client client contains the relevant information about the client/merchant who uses the checkout flow.
expiry_date_time Timestamp expiry_date_time is the expiry time of the created invoice. This parameter will enable merchants to to set their own invoice expiry so that it matches their business process better. Value will be on UTC timestamp. If the field is omitted, default 24 hour expiry time will be placed instead. For example if value equals 2021-05-01T00:00:00Z, the transaction will expire at 01 May 2021 00:00. However if it’s empty, the transaction will expire 24 hours after checkout request is successful.
unique_amount UniqueAmountType UniqueAmount sets the option for enabling the cents reconciliation workaround logic which modifies the transaction amount in attempt to make it unique for the time period.
Objects
Customer
Name Type Description
fname string The end user’s first name.
lname string The end user’s last name.
mname string The end user’s middle name.
email string The customer’s contact email.
mobile string The end user’s mobile phone number.
phone string Phone is the customer’s Landline number.
customer_id string An additional user identifier, such as a UUID, that the Brankas client can optionally add to the customer object.
address Address Address is the customer’s address.
Amount
Name Type Description
cur CurrencyISO4217 Cur is the currency.
num string Num is the numeric value.
AccountInfo
Name Type Description
type AccountInfoType The type of info relating to a bank transfer account. Please fill in with “BANK”.
bank_code BankCode Brankas bank code. Only present when type is BANK. Bank Codes differ depending on whether they are used as the source or the destination of a funds transfer. Bank code parameter is optional. If bank code is set in checkout request, then Brankas Tap would show the bank selector page. If it is not set, then Brankas Tap would not show the bank selector page. For the full list and details on bank codes, please see the Bank Codes section.
country CountryISO3166 The country where the end user’s bank is based using ISO 3166 Alpha-2 country codes. Currently supports: Indonesia: ID, Philippines: PH, & Thailand: TH.
Client
Name Type Description
display_name string DisplayName of the client’s app.
logo_url string LogoURL is the link to the client’s logo
return_url string ReturnURL is the return path for the app redirection after a checkout transaction has been accomplished
fail_url string FailURL is the return path for the app redirection after a checkout transaction has failed or hits an error state.
deep_link bool If DeepLink is set at “true” it indicates that the client wants to display remember me feature in the bank login form
short_redirect_uri bool ShortRedirectURI indicates that the client wanted to have short_redirect_uri generated on the redirect_uri. If the parameter “fname” is set, then the short_redirect_uri would include end user’s first name in the link, e.g. “https://direct.bnk.to/tap/FjTqkP3Q/Sarah”
Timestamp
Name Type Description
seconds int64
nanos int32
Address
Name Type Description
line1 string Line1 is the customer’s first line of address
line2 string Line2 is the customer’s second line of address
city string City is the customer’s city
province string Province is the customer’s province
zip_code string ZipCode is the customer’s postal code
country string Country is the country the customer is located in
Enums
PaymentChannelType

PaymentChannelType is the payment rail that will be used to facilitate the fund transfer using settlement partners. Allows for the selection of established settlement partners to be used in order to move fund transfer to the beneficiary bank accounts.

Value Description
PH_PAYNAMICS Process inter-bank fund transfer via Paynamics settlements service, a Brankas Partner.
ID_BANK_MEGA_IPG Process inter-bank fund transfer via Bank Mega - IPG settlements service.
ID_SHOPEE Process intra/inter-bank fund transfer via Shopee Pay QRIS acquirer.
UniqueAmountType

UniqueAmountType for cents reconciliation workaround

Value Description
NONE NONE will not apply any modification to the transaction amount
ADD ADD will apply additional centavos to the transaction amount
SUBTRACT SUBTRACT will deduct centavos to the transaction amount
CurrencyISO4217

CurrencyISO4217 iso is the 3 digit currency that will be used as standard currency type on fast checkout. see: https://en.wikipedia.org/wiki/ISO_4217

Value Description
UNKNOWN_CURRENCY
AFN
EUR
ALL
DZD
USD
AOA
XCD
ARS
AMD
AWG
AUD
AZN
BSD
BHD
BDT
BYR
BZD
XOF
BMD
BTN
BOV
BAM
BWP
NOK
BRL
SGD
BGN
BIF
KHR
XAF
CAD
CVE
KYD
CLP
CNY
COP
KMF
CDF
NZD
CRC
HRK
CUC
CZK
DKK
DJF
DOP
EGP
ERN
ETB
FKP
FJD
XPF
GMD
GEL
GHS
GIP
GTQ
GBP
GNF
GYD
HNL
HKD
HUF
ISK
INR
IDR
IRR
IQD
IMP
ILS
JMD
JPY
JEP
JOD
KZT
KES
KPW
KRW
KWD
KGS
LAK
LBP
LSL
LRD
LYD
CHF
MKD
MGA
MWK
MYR
MVR
MRO
MUR
MXN
MDL
MNT
MAD
MZN
MMK
NAD
NPR
ANG
NIO
NGN
OMR
PKR
PGK
PYG
PEN
PHP
PLN
QAR
RON
RUB
RWF
WST
STD
SAR
RSD
SCR
SLL
SBD
SOS
ZAR
SSP
LKR
SHP
SDG
SRD
SZL
SEK
SYP
TWD
TJS
TZS
THB
TOP
TTD
TND
TRY
TMT
UGX
UAH
ARE
UYU
UZS
VUV
VEF
VND
YER
ZRN
ZMW
AccountInfoType

AccountInfoType is the type of info relating to a bank transfer account.

Value Description
AccountInfoTypeUNKNOWN Unrecognised info type.
ACCOUNT Account type.
PROFILE Profile type.
BANK Bank type.
MSISDN Phone number type.
BankCode
Value Description
DUMMY_BANK_PERSONAL Brankas Bank. A test bank that you can make sandboxed calls to as part of integration testing.
MANDIRI_PERSONAL PT. Bank Mandiri (Persero), TBK. Personal/retail account.
BCA_PERSONAL PT. Bank Central Asia, TBK. Personal/retail account.
BNI_PERSONAL PT. Bank Negara Indonesia (Persero), TBK. Personal/retail account.
BRI_PERSONAL PT. Bank Rakyat Indonesia (Persero), TBK.
CIMB_PERSONAL PT Bank CIMB Niaga Tbk. Personal/retail account.
BDO_PERSONAL Banco De Oro Unibank, Inc. (BDO). Personal/retail account.
BPI_PERSONAL Bank of the Philippine Islands (BPI). Personal/retail account.
PNB_PERSONAL Philippine National Bank (PNB). Personal/retail account.
UNIONBANK_PERSONAL Union Bank of the Philippines. Personal/retail account.
METROBANK_PERSONAL The Metropolitan Bank and Trust Company (Metrobank). Personal/retail account.
RCBC_PERSONAL The Rizal Commercial Banking Corporation (RCBC). Personal/retail account.
SCB_PERSONAL Siam Commercial Bank of Thailand. Personal/retail account.
KASIKORNBANK_PERSONAL Kasikornbank Thailand. Personal/retail account.
CountryISO3166
Value Description
ID Indonesia
PH Philippines
TH Thailand

Responses

Response body

Name Type Description
transaction_id string transaction_id is the unique identifier assigned to the fund transfer request generated by Brankas.
redirect_uri string redirect_uri is the URL that end users need to be redirected to in order to authorize the fund transfer and complete the transaction.
short_redirect_uri string short_redirect_uri is the shortened version of the redirect_uri.

Response codes

Status Description
200 Request executed successfully.
404 Returned when the resource is not found.
400 Returned when the request body is malformatted or does not match the expected request.
401 Returned when the request does not contains the user’s credentials.
403 Returned when the user does not have permission to access the resource.
500 Returned when an unexpected error occured on the server side.

Retrieve the transactions

RetrieveTransactions returns the details of transactions. By specifying the transaction_id of the relevant transaction as a query parameter, only the record specific to that transaction will be retrieved. If no transaction_id is specified in the query parameter, the response will return all transaction records and list them from most recent to latest. Retrieved transaction records are paginated.

curl -X GET \
	https://direct.sandbox.bnk.to/v1/transaction \
	-H 'x-api-key: USE_YOUR_API_KEY'

HTTP Request

GET https://direct.sandbox.bnk.to/v1/transaction

Responses

Response body

Name Type Description
transactions []Transaction transactions are the transactions that match the filters of a request.
next_page int32 next_page is the number of the next page that can be returned. if it is 0, there are no more pages available.
total_count int32 total_count of the transactions matched by the query filters
Objects
Transaction
Name Type Description
transaction_id string TransactionID is the transaction firestore document identifier.
org_id string OrgID is the organization identifier.
destination_account_id string destination_account_id is the string ID corresponding to the bank information of the recipient.
business_info_id string business_info_id contains the unique identifier of the business information object.
from AccountInfo from is the source account information. Make sure the bank code on this field is set, this bank will be used to initiate the transfer.
to DestinationAccountInfo to is the destination account information.
amount Amount Amount is the transfer amount.
customer Customer Customer contains customer information
consent_granted bool ConsentGranted is the flag that represents if the user gave the system its consent.
additional_details AdditionalDetails additional_details contains the additional optional information related to the transaction.
payment_channel PaymentChannelType PaymentChannel is the desired payment channel to use for the fund transfer.
settlement_id string SettlementID is the settlement identifier.
reference_id string ReferenceID is the client identifier for an invoice object
user_memo string UserMemo is the user supplied memo line (e.g. RRN).
bank_memo string BankMemo is the bank supplied memo line (e.g. confirmation number).
attempts int32 Attempts is the count of transactional attempts.
error string Error holds the error text if an error occured during the transfer.
status FundTransferTaskStatus Status is the fund transfer task status of the transaction.
status_desc string StatusDesc contains the description about the status for this transaction.
status_code string StatusCode contains the status code for this transaction.
finish Timestamp Finish is the timestamp the task was completed.
created Timestamp Created is a timestamp the task was created.
updated Timestamp Updated is the timestamp the task was modified.
AccountInfo
Name Type Description
type AccountInfoType The type of info relating to a bank transfer account.
bank_code BankCode Brankas bank code. Only present when type is BANK. Bank Codes differ depending on whether they are used as the source or the destination of a funds transfer. For the full list and details on bank codes, please see the Bank Codes section.
country CountryISO3166 The country where the end user’s bank is based using ISO 3166 Alpha-2 country codes. Currently supports: Indonesia: ID, Philippines: PH, & Thailand: TH.
DestinationAccountInfo
Name Type Description
type AccountInfoType Type is the account info type.
bank_code DestinationBankCode BankCode is a bank code. Only present when type is BANK.
account_number string AccountNumber is a bank account number.
identifier string Identifier is a unique account ID, profile ID, or the bank account number and is interpreted based on the account info type.
holder_name string HolderName is the name of the account holder. This field is DEPRECATED in favor of the HolderFirstName, HolderMiddleName and HolderLastName which we join to come up with a full name.
holder_first_name string HolderFirstName is the first name of the account holder.
holder_middle_name string HolderMiddleName is the middle name of the account holder.
holder_last_name string HolderLastName is the last name of the account holder.
email_address string EmailAddress is the destination user email address.
mobile_country_code string MobileCountryCode is the mobile country dial code.
mobile_number string MobileNumber is the destination user mobile number.
address_line1 string AddressLine1 is the user destination address information.
address_line2 string AddressLine1 is the user destination address additional information.
city string City is the user destination residential city.
state string State is the user destination residential state.
country string Country is the user destination residential country.
Amount
Name Type Description
cur CurrencyISO4217 Cur is the currency.
num string Num is the numeric value.
Customer
Name Type Description
fname string The end user’s first name.
lname string The end user’s last name.
mname string The end user’s middle name.
email string The customer’s contact email.
mobile string The end user’s mobile phone number.
phone string Phone is the customer’s Landline number.
customer_id string An additional user identifier, such as a UUID, that the Brankas client can optionally add to the customer object.
address Address Address is the customer’s address.
AdditionalDetails
Name Type Description
qr_code string QRCodeRawData contains the raw text data that will be used to recreate the QRCode.
account_alias_id string AccountAliasID is the alternative identifier of the destination account.
to_address_line1 string ToAddressLine1 is the user destination address information.
to_address_line2 string ToAddressLine1 is the user destination address additional information.
to_city string ToCity is the user destination residential city.
to_state string ToState is the user destination residential state.
to_country string ToCountry is the user destination residential country.
terms_of_use_version string TermsOfUseVersion is the version number of the terms of use document that the user interacted unto.
privacy_policy_version string PrivacyPolicyVersion is the version number of the privacy policy document that the user interacted unto.
user_id_hash string UserIdHash is the hash of the end user’s bank code and online banking username used to uniquely identify an end user across clients
user_access_hash string UserAccessHash is the hash of the end user’s bank code and online banking credentials used to uniquely identify an end user based on their access credentials
user_account_hash string UserAccountHash is the hash of the end user’s bank code and specific bank account used for the transaction used to identify if the end user is using the same or different bank accounts
via Via Via indicates fund transfer rail used for the transfer
bank_fee Amount BankFee indicates the amount that will be deducted from the end user’s account as a fee from the bank for performing the fund transfer
settlement_identifier string SettlementIdentifier contains the primary identifier used by the settlement partner for this type of bank.
settlement_identifier_alias string SettlementIdentifierAlias contains the alias or secondary identifier used by the settlement partner for this type of bank.
Timestamp
Name Type Description
seconds int64
nanos int32
Address
Name Type Description
line1 string Line1 is the customer’s first line of address
line2 string Line2 is the customer’s second line of address
city string City is the customer’s city
province string Province is the customer’s province
zip_code string ZipCode is the customer’s postal code
country string Country is the country the customer is located in
Enums
PaymentChannelType

PaymentChannelType is the payment rail that will be used to facilitate the fund transfer using settlement partners. Allows for the selection of established settlement partners to be used in order to move fund transfer to the beneficiary bank accounts.

Value Description
PH_PAYNAMICS Process inter-bank fund transfer via Paynamics settlements service, a Brankas Partner.
ID_BANK_MEGA_IPG Process inter-bank fund transfer via Bank Mega - IPG settlements service.
ID_SHOPEE Process intra/inter-bank fund transfer via Shopee Pay QRIS acquirer.
FundTransferTaskStatus

Status is the fund transfer status.

Value Description
TransferStatus_CREATED
TransferStatus_TFA_AWAIT
TransferStatus_COMPLETED
TransferStatus_ERROR
TransferStatus_LOGIN_ERROR
TransferStatus_INVOICE_CREATED
TransferStatus_AWAITING_LOGIN
TransferStatus_AWAITING_LOGIN_TFA
TransferStatus_AWAITING_ACCOUNT_SELECT
TransferStatus_AWAITING_TRANSFER_TFA
TransferStatus_IN_PROGRESS
TransferStatus_EXPIRED
TransferStatus_FLAGGED
TransferStatus_CANCELLED
TransferStatus_DENIED
TransferStatus_FAILED
AccountInfoType

AccountInfoType is the type of info relating to a bank transfer account.

Value Description
AccountInfoTypeUNKNOWN Unrecognised info type.
ACCOUNT Account type.
PROFILE Profile type.
BANK Bank type.
MSISDN Phone number type.
BankCode
Value Description
UNKNOWN_BANK
DUMMY_BANK_PERSONAL Brankas Bank. A test bank that you can make sandboxed calls to as part of integration testing.
DUMMY_BANK_BCA_PERSONAL BCA dummy bank that can make sandboxed calls as part of integration testing. (DEPRECATED)
MANDIRI_PERSONAL ID PT. Bank Mandiri (Persero), TBK.
BCA_PERSONAL PT. Bank Central Asia, TBK.
BNI_PERSONAL PT. Bank Negara Indonesia (Persero), TBK.
BRI_PERSONAL PT. Bank Rakyat Indonesia (Persero), TBK.
BCA_CORPORATE
CIMB_PERSONAL PT Bank CIMB Niaga Tbk
BDO_PERSONAL PH Banco De Oro Unibank, Inc. (BDO).
BPI_PERSONAL Bank of the Philippine Islands (BPI).
PNB_PERSONAL Philippine National Bank (PNB).
UNIONBANK_PERSONAL
UNIONBANK_CORPORATE
METROBANK_PERSONAL The Metropolitan Bank and Trust Company (Metrobank).
RCBC_PERSONAL The Rizal Commercial Banking Corporation (RCBC).
CLRB_PERSONAL Cebuana Lhuillier Rural Bank (CLRB).
KOMO_PERSONAL Komo / EastWest Rural Bank
EASTWEST_PERSONAL EastWest Bank
SCB_PERSONAL TH
KASIKORNBANK_PERSONAL
CountryISO3166
Value Description
ID Indonesia
PH Philippines
TH Thailand
DestinationBankCode
Value Description
DUMMY_BANK_DESTINATION
ID_BCA
ID_BCA_SYR
ID_BNI
ID_BNI_SYR
ID_BRI
ID_BRI_SYR
ID_MANDIRI
ID_MANDIRI_SYR
ID_BTN
ID_BTN_SYR
ID_PERMATA
ID_PERMATA_SYR
ID_DNMN
ID_DNMN_SYR
ID_BTPN
ID_BTPN_SYR
ID_OCBC
ID_OCBC_SYR
ID_MAYBANK
ID_MAYBANK_SYR
ID_CIMB
ID_CIMB_SYR
ID_PAN
ID_PAN_SYR
ID_MEGA
ID_MEGA_SYR
ID_BKP
ID_BKP_SYR
ID_DKI
ID_DKI_SYR
ID_BJB
ID_BJB_SYR
ID_JATIM
ID_JATIM_SYR
ID_HSBC
ID_DBS
ID_STAN
ID_UOB
ID_CITI
PH_BDO
PH_BPI
PH_BPIF
PH_METRO
PH_PNB
PH_PNBS
PH_RCBC
PH_RCBCS
PH_SB
PH_SBS
PH_UB
PH_CLRB
PH_GXI
PH_GBY
PH_LBP
PH_PMP
PH_PSB
PH_RSB
PH_CB
PH_CBS
TH_KBANK
PH_ALLBANK
PH_SUNSB
PH_STERLING
PH_MBSMB
PH_AUB
PH_BOC
PH_MAYBANK
PH_PBCOM
PH_CTBC
PH_EWB
PH_EQB
PH_OMNIPAY
PH_UCPB
PH_PHILTRUST
PH_WDB
PH_DUNGGANUN
PH_UCPBSB
PH_ISLA
PH_PRBC
PH_PBB
PH_PVB
PH_YSBP
PH_MABUHAY
PH_CTBCPH
PH_ING
PH_QCRB
PH_BDONB
PH_EWBRB
TH_SCB
PH_STAN
PH_HSBC
PH_CITI
PH_BOA
PH_UOB
PH_TOKYO
PH_MICB
PH_DBP
PH_ANZ
PH_KEB_HANA
PH_CHASE
PH_FCB
PH_MIZUHO
PH_DBS
PH_BBL
PH_CHINA
PH_SUMITOMO_MITSUI
PH_SHINHAN
PH_IBK
PH_STARPAY
PH_QUEENBANK
PH_INNOVATIVE_BANK
PH_AAIIB
PH_PRODUCERSSBC
PH_BPI_BANKO
PH_CIMB
PH_BANKFLORIDAPH
PH_GUINOBATAN
PH_HSBCSB
PH_CAMALIG
PH_COUNTRY_BUILDERS
PH_RANGAY_BANK
PH_COINSPH
PH_CARDBANK
CurrencyISO4217

CurrencyISO4217 iso is the 3 digit currency that will be used as standard currency type on fast checkout. see: https://en.wikipedia.org/wiki/ISO_4217

Value Description
UNKNOWN_CURRENCY
AFN
EUR
ALL
DZD
USD
AOA
XCD
ARS
AMD
AWG
AUD
AZN
BSD
BHD
BDT
BYR
BZD
XOF
BMD
BTN
BOV
BAM
BWP
NOK
BRL
SGD
BGN
BIF
KHR
XAF
CAD
CVE
KYD
CLP
CNY
COP
KMF
CDF
NZD
CRC
HRK
CUC
CZK
DKK
DJF
DOP
EGP
ERN
ETB
FKP
FJD
XPF
GMD
GEL
GHS
GIP
GTQ
GBP
GNF
GYD
HNL
HKD
HUF
ISK
INR
IDR
IRR
IQD
IMP
ILS
JMD
JPY
JEP
JOD
KZT
KES
KPW
KRW
KWD
KGS
LAK
LBP
LSL
LRD
LYD
CHF
MKD
MGA
MWK
MYR
MVR
MRO
MUR
MXN
MDL
MNT
MAD
MZN
MMK
NAD
NPR
ANG
NIO
NGN
OMR
PKR
PGK
PYG
PEN
PHP
PLN
QAR
RON
RUB
RWF
WST
STD
SAR
RSD
SCR
SLL
SBD
SOS
ZAR
SSP
LKR
SHP
SDG
SRD
SZL
SEK
SYP
TWD
TJS
TZS
THB
TOP
TTD
TND
TRY
TMT
UGX
UAH
ARE
UYU
UZS
VUV
VEF
VND
YER
ZRN
ZMW
Via

Via is the fund transfer rail enum.

Value Description
UNKNOWN_Via
INTRABANK
IDONLINE
IDLLG
IDRTGS
PHINSTAPAY
PHPESONET

Example:

{
  "transactions": [
    {
      "transaction_id": "string",
      "org_id": "string",
      "destination_account_id": "string",
      "business_info_id": "string",
      "from": {
        "type": "BANK",
        "bank_code": "DUMMY_BANK_PERSONAL",
        "identifier": "xxxxxx0000",
        "holder_name": "Test User"
      },
      "to": {
        "type": "BANK",
        "bank_code": "DUMMY_BANK_DESTINATION",
        "identifier": "xxxxx1234",
        "holder_name": "Test Recipient Account Holder"
      },
      "amount": {
        "cur": "CurrencyISO4217",
        "num": "string"
      },
      "customer": {
        "fname": "string",
        "lname": "string",
        "mname": "string",
        "email": "string",
        "mobile": "string",
        "phone": "string",
        "customer_id": "string",
        "address": {
          "line1": "string",
          "line2": "string",
          "city": "string",
          "province": "string",
          "zip_code": "string",
          "country": "string"
        }
      },
      "consent_granted": "bool",
      "additional_details": {
        "account_alias_id": "xyz321",
        "terms_of_use_version": "1.0.1",
        "privacy_policy_version": "1.0.1",
        "user_id_hash": "7c5ec69d9ef4c2067fbea4eaa79e837ff2b76a2f3ba73714c55fe992bebb3a3b",
        "user_access_hash": "0e9685ecf2c74b4ed296aab4793b6ec209c306d5ebfa7025aca62c6f7c8ba25d",
        "user_account_hash": "9a310918ca530c9a1e6f34385af5827ad02c89d668bc61623adcb46a43860ecc",
        "via": "INTRABANK",
        "bank_fee": {
          "cur": "IDR",
          "num": "0"
        }
      },
      "payment_channel": "PaymentChannelType",
      "settlement_id": "string",
      "reference_id": "string",
      "user_memo": "string",
      "bank_memo": "string",
      "attempts": "int32",
      "error": "string",
      "status": "FundTransferTaskStatus",
      "status_desc": "string",
      "status_code": "string",
      "finish": {
        "seconds": "int64",
        "nanos": "int32"
      },
      "created": {
        "seconds": "int64",
        "nanos": "int32"
      },
      "updated": {
        "seconds": "int64",
        "nanos": "int32"
      }
    }
  ],
  "next_page": 2,
  "total_count": 25
}

Response codes

Status Description
200 Request executed successfully.
404 Returned when the resource is not found.
400 Returned when the request body is malformatted or does not match the expected request.
401 Returned when the request does not contains the user’s credentials.
403 Returned when the user does not have permission to access the resource.
500 Returned when an unexpected error occured on the server side.

Retrieve the transfers

RetrieveTransfer returns the full details of a fund transfer request. By specifying the transfer_id of the relevant transaction as a query parameter, only the record specific to that transfer will be retrieved. If no transfer_id is specified in the query parameter, the response will return all transaction records and list them from most recent to latest. Retrieved transaction records are paginated.

curl -X GET \
	https://direct.sandbox.bnk.to/v1/transfer \
	-H 'x-api-key: USE_YOUR_API_KEY'

HTTP Request

GET https://direct.sandbox.bnk.to/v1/transfer

Responses

Response body

Name Type Description
transfers []Transfer transfers are the transfers that match the filters of a request.
next_page int32 next_page is the number of the next page that can be returned. if it is 0, there are no more pages available.
total_count int32 total_count of the transactions matched by the query filters
Objects
Transfer
Name Type Description
status Status status indicates the current status of the transfer.
from AccountInfo from is the source account information.
to DestinationAccountInfo to is the destination account information.
amount Amount amount is the transaction amount specified in the checkout request.
user_memo string user_memo is a client defined remarks attached to the transfer in the memo line (e.g. RRN). It is taken from memo parameter in the checkout request.
bank_memo string bank_memo is a bank-supplied memo line (e.g. confirmation number, payment reference code, or transaction ID of the fund transfer).
created Timestamp created is a timestamp when the transfer transaction was initiated.
completed Timestamp completed is a timestamp when the transfer transaction was fully processed and completed.
payment_channel string payment channel is the desired payment channel to be used for transfers using settlement partners. Allows for the selection of established settlement partners to be used in order to facilitate a transfer.
customer Customer customer is the end user’s identifying and contact information that allows transactions to be attributed to a specific end user.
transfer_id string transfer_id is the internal transfer transaction identifier.
updated Timestamp updated is the timestamp when the transfer was modified.
reference_id string reference_id is the client identifier for an invoice object.
org_id string org_id is the unique organization identifier.
consent_granted bool consent_granted is the flag that represents if the user gave the system its consent.
additional_details AdditionalDetails additional_details contains the additional optional information related to the transaction such as terms of use version, privacy policy version, bank rail used, and bank fee.
expiry_date_time Timestamp expiry_date_time is the expiry time of the created invoice.
status_code string status_code indicates the current status code of the transfer.
status_desc string status_desc indicates the accompanying description of the given status code of the transfer.
orig_amount Amount OrigAmount is the original transfer amount.
AdditionalDetails
Name Type Description
qr_code string QRCodeRawData contains the raw text data that will be used to recreate the QRCode.
account_alias_id string AccountAliasID is the alternative identifier of the destination account.
to_address_line1 string ToAddressLine1 is the user destination address information.
to_address_line2 string ToAddressLine1 is the user destination address additional information.
to_city string ToCity is the user destination residential city.
to_state string ToState is the user destination residential state.
to_country string ToCountry is the user destination residential country.
terms_of_use_version string TermsOfUseVersion is the version number of the terms of use document that the user interacted unto.
privacy_policy_version string PrivacyPolicyVersion is the version number of the privacy policy document that the user interacted unto.
user_id_hash string UserIdHash is the hash of the end user’s bank code and online banking username used to uniquely identify an end user across clients
user_access_hash string UserAccessHash is the hash of the end user’s bank code and online banking credentials used to uniquely identify an end user based on their access credentials
user_account_hash string UserAccountHash is the hash of the end user’s bank code and specific bank account used for the transaction used to identify if the end user is using the same or different bank accounts
via Via Via indicates fund transfer rail used for the transfer
bank_fee Amount BankFee indicates the amount that will be deducted from the end user’s account as a fee from the bank for performing the fund transfer
settlement_identifier string SettlementIdentifier contains the primary identifier used by the settlement partner for this type of bank.
settlement_identifier_alias string SettlementIdentifierAlias contains the alias or secondary identifier used by the settlement partner for this type of bank.
Enums
Status

Status is the possible statuses of a transfer or account listing operation.

Value Description
PENDING Pending operation.
AWAITING_TFA Awaiting TFA authentication.
SUCCESS Successful operation.
ERROR Error during operation.
LOGIN_ERROR Login Error.
INVOICE_CREATED Checkout invoice created.
AWAITING_LOGIN Login in progress.
AWAITING_LOGIN_TFA Awaiting login TFA Authentication.
AWAITING_ACCOUNT_SELECT Awaiting account selection.
AWAITING_TRANSFER_TFA Awaiting transfer TFA Authentication.
IN_PROGRESS Transfer is in progress.
EXPIRED Transaction Expired.
FLAGGED Transaction Flagged - receiver needs to do manual verification and settlement.
CANCELLED Transaction Cancelled - sender cancelled the transaction.
DENIED Transaction Denied - sender denied the consent.
FAILED Transaction Failed - receiver was not able to receive the funds.
Via

Via is the fund transfer rail enum.

Value Description
UNKNOWN_Via
INTRABANK
IDONLINE
IDLLG
IDRTGS
PHINSTAPAY
PHPESONET

Example:

{
  "transfers": [
    {
      "status": "SUCCESS",
      "from": {
        "type": "BANK",
        "bank_code": "DUMMY_BANK_PERSONAL",
        "identifier": "xxxxxx0000",
        "holder_name": "Test User"
      },
      "to": {
        "type": "BANK",
        "bank_code": "DUMMY_BANK_DESTINATION",
        "identifier": "xxxxx1234",
        "holder_name": "Test Recipient Account Holder"
      },
      "amount": {
        "cur": "IDR",
        "num": "10000"
      },
      "user_memo": "A note sent via email to customer",
      "bank_memo": "PC-20190807-40266526",
      "created": "2019-08-30T04:31:02.395149Z",
      "completed": "2019-08-30T04:33:53.124922Z",
      "payment_channel": "PH_PAYNAMICS",
      "settlement": {
        "settlement_id": "DMY_BBANK-20190807-40266526",
        "settlement_response_id": "107341390436731840",
        "num": "GR001",
        "settlement_status": "Transaction Successful",
        "settlement_timestamp": "2020-04-02 14:23:39 +08:00"
      },
      "customer": {
        "fname": "John",
        "lname": "Johnson",
        "mname": "Joseph",
        "customer_id": "4f30b317-f98b-4454-bc05-7c4a2e48ec0d",
        "email": "john.johnson@domain.com",
        "mobile": "+62-283-5559-907"
      },
      "transfer_id": "f6355a01-e32b-426e-b2af-85366d305743",
      "updated": {
        "seconds": "int64",
        "nanos": "int32"
      },
      "reference_id": "9005376336",
      "bank_ref_code": "string",
      "org_id": "5338cfca-7ff4-11eb-a920-476c005dcafe",
      "consent_granted": true,
      "additional_details": {
        "account_alias_id": "xyz321",
        "terms_of_use_version": "1.0.1",
        "privacy_policy_version": "1.0.1",
        "user_id_hash": "7c5ec69d9ef4c2067fbea4eaa79e837ff2b76a2f3ba73714c55fe992bebb3a3b",
        "user_access_hash": "0e9685ecf2c74b4ed296aab4793b6ec209c306d5ebfa7025aca62c6f7c8ba25d",
        "user_account_hash": "9a310918ca530c9a1e6f34385af5827ad02c89d668bc61623adcb46a43860ecc",
        "via": "INTRABANK",
        "bank_fee": {
          "cur": "IDR",
          "num": "0"
        }
      },
      "expiry_date_time": "2021-05-01T00:00:00Z",
      "status_code": "DIRDXXX2000",
      "status_desc": "generic success",
      "orig_amount": {
        "cur": "IDR",
        "num": "10000"
      }
    }
  ],
  "next_page": 2,
  "total_count": 25
}

Response codes

Status Description
200 Request executed successfully.
404 Returned when the resource is not found.
400 Returned when the request body is malformatted or does not match the expected request.
401 Returned when the request does not contains the user’s credentials.
403 Returned when the user does not have permission to access the resource.
500 Returned when an unexpected error occured on the server side.

Send TFA request

Send two factor authentication request.

curl -X POST \
	https://direct.sandbox.bnk.to/v1/tfa \
	-H 'x-api-key: USE_YOUR_API_KEY' \
	-d '{
		"purpose": "BankCredentialLogin",
		"purpose_id": "123_transfer_id",
		"token": "123456",
		"transfer_id": "string",
		"option": "OptionalChallengeType",
		"multiple": [
			{
				"type": "OptionalChallengeType",
				"code": "string"
			}
		]
	}'

HTTP Request

POST https://direct.sandbox.bnk.to/v1/tfa

Body Parameters

Name Type Description
purpose TFAPurpose Purpose defines what this TFA code should be used for.
purpose_id string purpose_id is the identifier for the object that this TFA token will be used for. For example, if purpose==BankCredentialLogin, purpose_id will be a bankcredential_id.
token string Token is the actual TFA / OTP code string the end user needs to submit.
transfer_id string transfer_id is the identifier of the transfer transaction.
option OptionalChallengeType Option to change OTP generator, ex: SMS, MGENCODE
multiple []MultipleCode Multiple contains several tokens if multiple TFA code is needed.
Objects
MultipleCode
Name Type Description
type OptionalChallengeType
code string
Enums
TFAPurpose

TFAPurpose is the usage of the TFA code supplied in the TFAService request

Value Description
UnknownPurpose Unknown Purpose
BankCredentialLogin Used to login to a bank account
FundTransferAuthentication Used to perform login for fund transfer
OptionalChallengeType

OptionalChallengeType for change OTP generators

Value Description
OPTION_UNKNOWN default to unknown, when there is no option set
OPTION_SMS SMS are SMS-based challenge codes.
OPTION_MGENCODE MGENCODE or Mobile Generated Code, are usually challenge codes generated by bank applications.
OPTION_PIN

Responses

Response body

Name Type Description
status Status Status defines the result of the request, indicating whether or not the TFA token was successfully submitted to the relevant bank or if the operation resulted in an error.
auth_status AuthStatus AuthStatus defines the result of submitting the TFA code with the bank, indicating whether the challenge succeeded or failed.
status_msg string StatusMsg is the bank-specific response to a failed TFA challenge, qualifying the cause of the failure (such as an invalid or incomplete TFA code)
Enums
Status

Status is the possible statuses for a TFA operation

Value Description
UNKNOWN_Status Unknown operation occuring
ERROR Error during operation
SUCCESS Successful operation
AuthStatus

AuthStatus is the possible response status’ for a TFA operation

Value Description
UNKNOWN_AuthStatus Unknown Status
INCOMPLETE Incomplete TFA
COMPLETE Successful TFA

Example:

{
  "auth_status": "COMPLETE",
  "status": "SUCCESS"
}

Response codes

Status Description
200 Request executed successfully.
404 Returned when the resource is not found.
400 Returned when the request body is malformatted or does not match the expected request.
401 Returned when the request does not contains the user’s credentials.
403 Returned when the user does not have permission to access the resource.
500 Returned when an unexpected error occured on the server side.