About Payment Hub

API Payment Hub > About Payment Hub

Environment	BASE_URL
Staging	https://payment-hub.bnlstg.com
Production	https://paymenthub.bookandlink.com

API Responses

Each response provided by Payment Hub will have the following json format. Apart from the following json format, you can also check the state of the process you are carrying out via the http response code which is responded to by Payment Hub.

Success Response

{
  "success": true,
  "message": "This is success message",
  "data": ""
}

Fail Response

{
  "success": false,
  "message": "Unable to proccess",
  "data": ""
}

Field	Descriptions	type
Success	Indicates whether the process was successful or failed, the value of this field can be `true` if the process is successful and `false` if it fails	bool
Message	Provide a message or brief description of the process carried out on the Payment Hub	text
Data	This field can be anything depending on the endpoint used. Each endpoint has a different response	any

Refresh Client Auth Token

This endpoint is used to refresh the access token you have. The token given will have an expiration time, therefore you must periodically refresh the token every day. The token will be valid for 24 hours and the Reset token will be valid for 7 days (168 hours). Once the token reset process is carried out, the token will be regenerated. Therefore, every time you refresh the token, you must ensure that the response is stored properly in your storage.

POST: BASE_URL/api/v1/auth/reset-token

curl --location 'BASE_URL/api/v1/auth/reset-token' 
\ --header 'Content-Type: application/json' 
\ --header 'Accept: application/json' 
\ --header 'Authorization: Bearer eIpprkXsrmnkX5HsGQVtPkBqIeAafpbyY9vC4aCK'

Header Parameters

Field	Descriptions	type
Authorization	Bearer + `client_refresh_token`	text

Response Parameters

{
    "success": true,
    "message": "Token reset Successfully",
    "data": {
        "ID": "65f14d79efc850b3546384e7",
        "IpValidation": true,
        "Name": "Client",
        "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
        "RefreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
        "Ip": "127.0.0.1",
        "Domain": "localhost",
        "TokenExpired": "2024-03-15T07:56:38.278Z",
        "RefreshTokenExpired": "2024-03-21T07:56:45.809Z"
    }
}

Field	Descriptions	type
ID	Represent the client unique ID	text
Name	Name of Payment Hub client	optional \| decimal
Token	Used for transaction processes such as creating transactions, refunds and checking transaction status. This token will be valid for 1 day from the execution of this endpoint	text
RefreshToken	This token is specifically used to carry out the token reset process.	text
IP	We will register this IP on our IP whitelist as middleware when you process the transaction	text
Domain	Represents the domain url of client	text
TokenExpired	The expiration date and time of the authentication token.	text
RefreshTokenExpired	The expiration date and time of the refresh token.	text

Error Codes

Error Code	Message	Description
401	Unauthorized	Refresh token was invalid
500	Server went wrong	An internal error occurred

Reset Client Refresh Token

This endpoint is used to regenerate client refresh token. Once the reset process is carried out, the refresh token will be regenerated. Therefore, every time you refresh the token, you must ensure that the response is stored properly in your storage.

POST: BASE_URL/api/v1/auth/reset-refresh-token

curl --location 'BASE_URL/api/v1/auth/reset-refresh-token' 
\ --header 'Content-Type: application/json' 
\ --header 'Accept: application/json' 
\ --header 'Authorization: Bearer eIpprkXsrmnkX5HsGQVtPkBqIeAafpbyY9vC4aCK'

Header Parameters

Field	Descriptions	type
Authorization	Bearer + `client_refresh_token`	text

Response Parameters

{
    "success": true,
    "message": "Refresh token reset Successfully",
    "data": {
        "ID": "65f14d79efc850b3546384e7",
        "IpValidation": true,
        "Name": "Client",
        "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
        "RefreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
        "Ip": "127.0.0.1",
        "Domain": "localhost",
        "TokenExpired": "2024-03-15T07:56:38.278Z",
        "RefreshTokenExpired": "2024-03-21T07:56:45.809Z"
    }
}

Field	Descriptions	type
ID	Represent the client unique ID	text
Name	Name of Payment Hub client	optional \| decimal
Token	Used for transaction processes such as creating transactions, refunds and checking transaction status. This token will be valid for 1 day from the execution of this endpoint	text
RefreshToken	This token is specifically used to carry out the token reset process.	text
IP	We will register this IP on our IP whitelist as middleware when you process the transaction	text
Domain	Represents the domain url of client	text
TokenExpired	The expiration date and time of the authentication token	text
RefreshTokenExpired	The expiration date and time of the refresh token	text

Error Codes

Error Code	Message	Description
401	Unauthorized	Refresh token was invalid
500	Server went wrong	An internal error occurred

Reset All Token

This endpoint is used to regenerate both of client token and refresh token. You can use this endpoint if your token or refresh token has expired. The middleware will only check your refresh token is exists without checking the expiration time of the refresh token.

POST: BASE_URL/api/v1/auth/reset-all-token

curl --location 'BASE_URL/api/v1/auth/reset-all-token' 
\ --header 'Content-Type: application/json' 
\ --header 'Accept: application/json' 
\ --header 'Authorization: Bearer eIpprkXsrmnkX5HsGQVtPkBqIeAafpbyY9vC4aCK'

Header Parameters

Field	Descriptions	type
Authorization	Bearer + `client_refresh_token`	text

Response Parameters

{
    "success": true,
    "message": "All token reset Successfully",
    "data": {
        "ID": "65f14d79efc850b3546384e7",
        "IpValidation": true,
        "Name": "Client",
        "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
        "RefreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
        "Ip": "127.0.0.1",
        "Domain": "localhost",
        "TokenExpired": "2024-03-15T07:56:38.278Z",
        "RefreshTokenExpired": "2024-03-21T07:56:45.809Z"
    }
}

Field	Descriptions	type
ID	Represent the client unique ID	text
Name	Name of Payment Hub client	optional \| decimal
Token	Used for transaction processes such as creating transactions, refunds and checking transaction status. This token will be valid for 1 day from the execution of this endpoint	text
RefreshToken	This token is specifically used to carry out the token reset process.	text
IP	We will register this IP on our IP whitelist as middleware when you process the transaction	text
Domain	Represents the domain url of client	text
TokenExpired	The expiration date and time of the authentication token	text
RefreshTokenExpired	The expiration date and time of the refresh token	text

Error Codes

Error Code	Message	Description
401	Unauthorized	Refresh token was invalid
500	Server went wrong	An internal error occurred

Public Token

Public tokens are tokens that can be used for processes that are carried out directly through the client page without going through your backend. Some of the processes that are supported via the client are Tokenize & Charge Credit Card.

You can generate this token via Payment Hub and will be valid for 1 hour. This token can be generated multiple times without overwriting the token you generated previously.

POST: BASE_URL/api/v1/auth/public-token

curl --location 'BASE_URL/api/v1/auth/public-token' 
\ --header 'Content-Type: application/json' 
\ --header 'Accept: application/json' 
\ --header 'Authorization: Bearer eIpprkXsrmnkX5HsGQVtPkBqIeAafpbyY9vC4aCK'

Header Parameters

Field	Descriptions	type
Authorization	Bearer + `client_token`	text

Response Parameters

{
    "success": true,
    "message": "Public key generate successfully",
    "data": {
        "ID": "6603dc2629d598f1b3a32adc",
        "ClientId": "66021840b3239bdfc1dcd8db",
        "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ik9iamVjdElEKFwiNjYwMjE4NDBiMzIzOWJkZmMxZGNkOGRiXCIpIiwiR2VuZXJhdGVkQXQiOiIyMDI0LTAzLTI3VDE2OjQzOjE4LjEzOTkwNjYzNiswODowMCIsIlRva2VuVHlwZSI6InB1YmxpYyIsImV4cCI6MTcxMTUzMjU5OH0.sfw-Jg9OcL443VU4q1AXlYE2l8o3aqnHKneCA-xWVLM",
        "ExpiredAt": "2024-03-27T09:43:18.139Z"
    }
}

Field	Descriptions	type
ID	Represent the client unique ID	text
ClientId	Your Payment Hub Client ID	text
Token	Used for client side process	text
ExpiredAt	The expiration date and time of the public token	text

Error Codes

Error Code	Message	Description
401	Unauthorized	Refresh token was invalid
500	Server went wrong	An internal error occurred

Vendor Payment Gateway

Payment gateway vendors refer to the list of merchants that have been integrated with Payment Hub. Currently, there are 12 payment gateway who have been integrated.

Get Vendor List

GET: BASE_URL/api/v1/vendor-payment-gateway

curl --location 'BASE_URL/api/v1/vendor-payment-gateway' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9'

Response Parameters

{
    "success": true,
    "message": "Success",
    "data": [
        {
            "Name": "Xendit",
            "Code": "bW4YCvzqds",
            "Lang": [
                "EN",
                "ID"
            ],
            "PaymentMethod": [
                "CREDIT_CARD",
                "BCA",
                "BNI",
                "BSI",
                "BRI",
                "MANDIRI",
                "PERMATA",
                "SAHABAT_SAMPOERNA",
                "BNC",
                "ALFAMART",
                "INDOMARET",
                "OVO",
                "DANA",
                "SHOPEEPAY",
                "LINKAJA",
                "JENIUSPAY",
                "DD_BRI",
                "DD_BCA_KLIKPAY",
                "KREDIVO",
                "AKULAKU",
                "UANGME",
                "ATOME",
                "QRIS",
                "CREDIT_CARD",
                "7ELEVEN",
                "CEBUANA",
                "DD_BPI",
                "DD_UBP",
                "DD_RCBC",
                "DD_BDO_EPAY",
                "DP_MLHUILLIER",
                "DP_PALAWAN",
                "DP_ECPAY_LOAN",
                "PAYMAYA",
                "GRABPAY",
                "GCASH",
                "SHOPEEPAY",
                "BILLEASE",
                "CASHALO",
                "CREDIT_CARD",
                "PROMPTPAY"
            ],
            "Currency": [
                "IDR",
                "PHP",
                "THB",
                "VND"
            ],
            "Tokenize": true,
            "Tokenize3ds": true,
            "SharedCredential": false
        },
        {
            "Name": "Stripe",
            "Code": "J2fHptOnCv",
            "Lang": [
                "en-gb",
                "en-us",
                "id",
                "ja",
                "th",
                "ko",
                "zh-hk",
                "zh-cn",
                "zh-tw",
                "ms"
            ],
            "PaymentMethod": [],
            "Currency": [
                "USD",
                "IDR",
                "PHP",
                "THB",
                "MYR",
                "JPY",
                "CNY",
                "SGD",
                "KRW"
            ],
            "Tokenize": false,
            "Tokenize3ds": false,
            "SharedCredential": false
        },
        {
            "Name": "Paydollar",
            "Code": "XomO6TyQjP",
            "Lang": [
                "en",
                "zh-hant",
                "zh-hans",
                "ja",
                "th",
                "fr",
                "de",
                "ru",
                "es",
                "vi"
            ],
            "PaymentMethod": [
                "ALL",
                "CC",
                "VISA",
                "Master",
                "JCB",
                "AMEX",
                "Diners",
                "PPS",
                "PAYPAL",
                "CHINAPAY",
                "ALIPAY",
                "TENPAY",
                "99BIL",
                "MEPS",
                "SCB",
                "KTB",
                "UOB",
                "KRUNGSRIONLINE",
                "TMB",
                "IBANKING",
                "UPOP",
                "M2U",
                "CIMBCLICK",
                "OCTOPUS"
            ],
            "Currency": [
                "HKD",
                "USD",
                "SGD",
                "CNY",
                "JPY",
                "TWD",
                "AUD",
                "EUR",
                "GBP",
                "CAD",
                "MOP",
                "PHP",
                "THB",
                "MYR",
                "IDR",
                "KRW",
                "SAR",
                "NZD",
                "AED",
                "BND",
                "VND",
                "INR"
            ],
            "Tokenize": false,
            "Tokenize3ds": false,
            "SharedCredential": false
        },
        {
            "Name": "Reddot",
            "Code": "JFthgMzODB",
            "Lang": [
                "en",
                "id",
                "es",
                "fr",
                "de",
                "ja",
                "th",
                "zh",
                "zh_cn"
            ],
            "PaymentMethod": [],
            "Currency": [],
            "Tokenize": false,
            "Tokenize3ds": false,
            "SharedCredential": false
        },
        {
            "Name": "Komoju",
            "Code": "6EOzpRtapC",
            "Lang": [
                "en",
                "ja",
                "ko"
            ],
            "PaymentMethod": [
                "alipay",
                "alipay_hk",
                "amazon_pay",
                "tng",
                "gcash",
                "kakaopay",
                "truemoney",
                "dana",
                "au",
                "aupay",
                "bancontact",
                "bank_transfer",
                "banrisul",
                "bit_cash",
                "blik",
                "credit_card",
                "credit_card_korea",
                "credit_card_brazil",
                "culture_voucher",
                "cvs",
                "doku_wallet",
                "docomo",
                "dospara",
                "dragonpay",
                "enets",
                "epospay",
                "eps",
                "fpx",
                "giropay",
                "grabpayotp",
                "happy_money",
                "ideal",
                "japan_mobile",
                "konbini",
                "komoju_pay",
                "linepay",
                "merpay",
                "mobile",
                "multibanco",
                "mybank",
                "narvesen",
                "naverpay",
                "nanaco",
                "net_cash",
                "ovo",
                "pay_easy",
                "payco",
                "paypay",
                "paypost",
                "paysafe_card",
                "paysera",
                "payu",
                "perlas",
                "pix",
                "poli",
                "przelewy24",
                "rakutenpay",
                "sofortbanking",
                "softbank",
                "steam_prepaid_card",
                "unionpay",
                "web_money",
                "wechatpay",
                "paidy",
                "toss"
            ],
            "Currency": [
                "JPY",
                "USD",
                "EUR",
                "TWD",
                "KRW",
                "PLN",
                "GBP",
                "HKD",
                "SGD",
                "NZD",
                "AUD",
                "IDR",
                "MYR",
                "PHP",
                "THB",
                "CNY",
                "BRL",
                "CHF",
                "CAD",
                "VND"
            ],
            "Tokenize": true,
            "Tokenize3ds": true,
            "SharedCredential": true
        },
        {
            "Name": "Omise",
            "Code": "RwQCcDM569",
            "Lang": [
                "en",
                "ja",
                "th",
                "id"
            ],
            "PaymentMethod": [],
            "Currency": [
                "AUD",
                "CAD",
                "CHF",
                "CNY",
                "DKK",
                "EUR",
                "GBP",
                "HKD",
                "JPY",
                "MYR",
                "SGD",
                "THB",
                "USD"
            ],
            "Tokenize": true,
            "Tokenize3ds": false,
            "SharedCredential": false
        },
        {
            "Name": "Bimopay",
            "Code": "tXezKhseYS",
            "Lang": [
                "en",
                "zh-hant",
                "zh-hans",
                "ja",
                "th",
                "fr",
                "de",
                "ru",
                "es",
                "vi"
            ],
            "PaymentMethod": [
                "ALL",
                "CC",
                "VISA",
                "Master",
                "JCB",
                "AMEX",
                "Diners",
                "PPS",
                "PAYPAL",
                "CHINAPAY",
                "ALIPAY",
                "TENPAY",
                "99BIL",
                "MEPS",
                "SCB",
                "KTB",
                "UOB",
                "KRUNGSRIONLINE",
                "TMB",
                "IBANKING",
                "UPOP",
                "M2U",
                "CIMBCLICK",
                "OCTOPUS"
            ],
            "Currency": [
                "HKD",
                "USD",
                "SGD",
                "CNY",
                "JPY",
                "TWD",
                "AUD",
                "EUR",
                "GBP",
                "CAD",
                "MOP",
                "PHP",
                "THB",
                "MYR",
                "IDR",
                "KRW",
                "SAR",
                "NZD",
                "AED",
                "BND",
                "VND",
                "INR"
            ],
            "Tokenize": false,
            "Tokenize3ds": false,
            "SharedCredential": false
        },
        {
            "Name": "Siampay",
            "Code": "not33AXqwW",
            "Lang": [
                "en",
                "zh-hant",
                "zh-hans",
                "ja",
                "th",
                "fr",
                "de",
                "ru",
                "es",
                "vi"
            ],
            "PaymentMethod": [
                "ALL",
                "CC",
                "VISA",
                "Master",
                "JCB",
                "AMEX",
                "Diners",
                "PPS",
                "PAYPAL",
                "CHINAPAY",
                "ALIPAY",
                "TENPAY",
                "99BIL",
                "MEPS",
                "SCB",
                "KTB",
                "UOB",
                "KRUNGSRIONLINE",
                "TMB",
                "IBANKING",
                "UPOP",
                "M2U",
                "CIMBCLICK",
                "OCTOPUS"
            ],
            "Currency": [
                "HKD",
                "USD",
                "SGD",
                "CNY",
                "JPY",
                "TWD",
                "AUD",
                "EUR",
                "GBP",
                "CAD",
                "MOP",
                "PHP",
                "THB",
                "MYR",
                "IDR",
                "KRW",
                "SAR",
                "NZD",
                "AED",
                "BND",
                "VND",
                "INR"
            ],
            "Tokenize": false,
            "Tokenize3ds": false,
            "SharedCredential": true
        },
        {
            "Name": "Pesopay",
            "Code": "2RDZvEFAMr",
            "Lang": [
                "en",
                "zh-hant",
                "zh-hans",
                "ja",
                "th",
                "fr",
                "de",
                "ru",
                "es",
                "vi"
            ],
            "PaymentMethod": [
                "ALL",
                "CC",
                "VISA",
                "Master",
                "JCB",
                "AMEX",
                "Diners",
                "PPS",
                "PAYPAL",
                "CHINAPAY",
                "ALIPAY",
                "TENPAY",
                "99BIL",
                "MEPS",
                "SCB",
                "KTB",
                "UOB",
                "KRUNGSRIONLINE",
                "TMB",
                "IBANKING",
                "UPOP",
                "M2U",
                "CIMBCLICK",
                "OCTOPUS"
            ],
            "Currency": [
                "HKD",
                "USD",
                "SGD",
                "CNY",
                "JPY",
                "TWD",
                "AUD",
                "EUR",
                "GBP",
                "CAD",
                "MOP",
                "PHP",
                "THB",
                "MYR",
                "IDR",
                "KRW",
                "SAR",
                "NZD",
                "AED",
                "BND",
                "VND",
                "INR"
            ],
            "Tokenize": false,
            "Tokenize3ds": false,
            "SharedCredential": true
        },
        {
            "Name": "Cathay",
            "Code": "mlid6Rv36x",
            "Lang": [
                "EN-US",
                "ZH-TW",
                "JA-JP",
                "KO-KR"
            ],
            "PaymentMethod": [],
            "Currency": [
                "TWD"
            ],
            "Tokenize": false,
            "Tokenize3ds": false,
            "SharedCredential": true
        },
        {
            "Name": "Cibpaynow",
            "Code": "2mI6PWZao5",
            "Lang": [
                "EN"
            ],
            "PaymentMethod": [
                "CREDIT_CARD"
            ],
            "Currency": [
                "EUR",
                "USD",
                "GBP",
                "EGP"
            ],
            "Tokenize": false,
            "Tokenize3ds": false,
            "SharedCredential": false
        },
        {
            "Name": "LinePay",
            "Code": "bsvB4sgwMS",
            "Lang": [
                "en",
                "ja",
                "ko",
                "th",
                "zh_TW",
                "zh_CN"
            ],
            "PaymentMethod": [],
            "Currency": [
                "IDR",
                "USD",
                "JPY",
                "TWD",
                "THB"
            ],
            "Tokenize": false,
            "Tokenize3ds": false,
            "SharedCredential": false
        }
    ]
}

Field	Descriptions	type
ID	Representing the Vendor ID	text
Name	This is the vendor name of the payment gateway used. Currently, the only payment gateway available in Payment Hub is Xendit, Stripe, Paydollar, Bimopay, Pesopay, Siampay, Reddot, Komoju, Omise, Cathay, Linepay, Cibpaynow, and Nicepay	text
Code	This is the unique identifier for Vendor Payment Gateway	text
Lang	This column will contain a list of locales that can be used when creating transactions based on the vendor you use. Note : Stripe uses the chosen language to localize invoice emails and PDFs, receipt emails and PDFs, and credit note PDFs. The selected language will not be used on the payment link page.	array of string
PaymentMethod	This column will contain a list of payment method that can be used when creating transactions based on the vendor you use.	array of string
Currency	This column will contain a list of currencies that you can use based on vendor.	array of string
Tokenize	Indicate this vendor is allowed to create credit card token or not. See Tokenize & Charge Credit Card for more details.	boolean
Tokenize3ds	Indicate this vendor is allowed to create credit card 3ds token or not.	boolean

Payment Gateway

The payment gateway endpoint represents the third-party Payment Gateway that you have. When making a transaction, you will include which payment gateway you will use. Payment Hub will process the transaction according to the payment gateway you choose

Get Payment Gateway

GET: BASE_URL/api/v1/payment-gateway

curl --location 'BASE_URL/api/v1/payment-gateway' 
\ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9'

Response Parameters

{
  "success": true,
  "message": "Success.",
  "data": [
      {
          "ID": "65c314574bea7be0c0405e1d",
          "Code": "BNL001",
          "Credential": {
              "merchant_key": "xnd_development_xxx",
              "public_key": "xnd_public_development_xxx"
          },
          "vendor_payment_gateway": {
              "Name": "Xendit",
              "Code": "BNL001",
              "Lang": ["EN", "ID"],
              "PaymentMethod": ["CREDIT_CARD", "BCA", "BNI", "BSI", "BRI", "MANDIRI", "PERMATA", "SAHABAT_SAMPOERNA", "BNC", "ALFAMART", "INDOMARET", "OVO", "DANA", "SHOPEEPAY", "LINKAJA", "JENIUSPAY", "DD_BRI", "DD_BCA_KLIKPAY", "KREDIVO", "AKULAKU", "UANGME", "ATOME", "QRIS", "CREDIT_CARD", "7ELEVEN", "CEBUANA", "DD_BPI", "DD_UBP", "DD_RCBC", "DD_BDO_EPAY", "DP_MLHUILLIER", "DP_PALAWAN", "DP_ECPAY_LOAN", "PAYMAYA", "GRABPAY", "GCASH", "SHOPEEPAY", "BILLEASE", "CASHALO", "CREDIT_CARD", "PROMPTPAY"],
              "Currency": ["IDR", "PHP", "THB", "VND"],
              "Tokenize": true,
              "Tokenize3ds": true
          }
      },
      {
          "ID": "65c314574bea7be0c0405e1d",
          "Code": "BNL002",
          "Credential": null,
          "vendor_payment_gateway": {
              "Name": "Stripe",
              "Code": "BNL002",
              "Lang": ["en-gb", "en-us", "id", "ja", "th", "ko", "zh-hk", "zh-cn", "zh-tw", "ms"],
              "PaymentMethod": [],
              "Currency": ["USD", "IDR", "PHP", "THB", "MYR", "JPY", "CNY", "SGD", "KRW"],
              "Tokenize": false,
              "Tokenize3ds": false
          }
      }
  ]
}

Field	Descriptions	type
ID	Representing your Payment Gateway ID. Use this ID for fill the `payment_vendor` field on transactions processing.	text
Code	This is the unique identifier for Vendor Payment Gateway.	text
Credential	The response object from this field can change according to the name of the payment gateway you are using. If this column is empty, it indicates that the credential will use the default credential that Payment Hub has prepared.	object
vendor_payment_gateway	The vendor payment gateway object related to the payment gateway from payment gateway	object

Create Payment Gateway

POST: BASE_URL/api/v1/payment-gateway

Create without credential

curl --location 'BASE_URL/api/v1/payment-gateway' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ik9iamVjdElEKFwiNjU3ZmZkYjVkZmEwM2YxNTAxNzMyODRkXCIpIiwiR2VuZXJhdGVkQXQiOiIyMDI0LTAyLTEyVDE0OjQ3OjAyLjg2NzI0MTc5NSswODowMCIsIlRva2VuVHlwZSI6InRva2VuIiwiZXhwIjoxNzA3ODA2ODIyfQ.CyswFdah4qQSrevDTJlGxkxEACXCPNZxdMeSZf_w3Bk' \
--data '{
    "code": "BNL001"
}'

Create with credential

curl --location 'BASE_URL/api/v1/payment-gateway' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ik9iamVjdElEKFwiNjU3ZmZkYjVkZmEwM2YxNTAxNzMyODRkXCIpIiwiR2VuZXJhdGVkQXQiOiIyMDI0LTAyLTEyVDE0OjQ3OjAyLjg2NzI0MTc5NSswODowMCIsIlRva2VuVHlwZSI6InRva2VuIiwiZXhwIjoxNzA3ODA2ODIyfQ.CyswFdah4qQSrevDTJlGxkxEACXCPNZxdMeSZf_w3Bk' \
--data '{
    "code": "BNL001",
    "credential" : {
        "merchant_key": "xxx", 
        "public_key": "xxx"
    }
}'

Body Parameters

Field	Descriptions	type
code	This is the vendor code of the payment gateway used. Use the Vendor Payment Gateway endpoint to get the list of codes you can use.	text
credential	The request object from this field can change according to the name of the payment gateway you are using. The following are examples of objects from each payment gateway that will be responded to 1. Xendit `{"merchant_key": "", "public_key": ""}` 2. Stripe `{"publishable_key": "", "secret_key": ""}` 3. Paydollar `{"merchant_id": "", "merchant_api_password": "", "merchant_api_id": ""}` 4. Reddot `{"merchant_id": "", "secret_key": "", "access_key": ""}` 5. Komoju `{"publishable_key": "", "secret_key": ""}` 6. Omise `{"public_key": "", "secret_key": ""}` 7. Cathay `{"store_id": "", "cub_key": ""}` 8. Bimopay `{"merchant_id": "", "merchant_api_password": "", "merchant_api_id": ""}` 9. Siampay `{"merchant_id": "", "merchant_api_password": "", "merchant_api_id": ""}` 10. Pesopay `{"merchant_id": "", "merchant_api_password": "", "merchant_api_id": ""}` 11. LinePay `{"channel_id": "", "channel_secret": ""}` 12. Cibpaynow `{"merchant_id": "", "password": ""}` 13. Nicepay `{"mid": "", "key": ""}` This column is optional, if you create a payment gateway without credentials, we will use Payment Hub default credentials.	object \| optional

Response Parameters

{
    "success": true,
    "message": "Payment Gateway Created Successfully",
    "data": {
        "ID": "65c314574bea7be0c0405e1d",
        "Code": "BNL001",
        "Credential": {
            "merchant_key": "xxx",
            "public_key": "xxx"
        },
        "ClientId": "657f8ed390f51b5bb9be1a38"
    }
}

Field	Descriptions	type
ID	Representing your Payment Gateway ID	text
Code	This is the unique identifier for your Payment Gateway.	text
Credential	The response object from this field can change according to the name of the payment gateway you are using.	object
ClientId	Represent your ID in Payment Hub	string

Error Codes

Error Code	Message	Description
401	Unauthorized	The client token was invalid
400	Validation failed	Inputs are failing validation. The errors field contains details about which fields are violating validation.
500	Server went wrong	An internal error occurred

Update Payment Gateway

PUT: BASE_URL/api/v1/payment-gateway/{id}

curl --location --request PUT 'https://payment-hub.bnlstg.com/api/v1/payment-gateway/65baf6f2cb57af46294024f7' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
--header 'Content-Type: application/json' \
--data '{
    "code": "BNL001",
    "credential" : {
        "merchant_key": "", 
        "public_key": ""
    }
}'

Response Parameters

{
  "success": true,
  "message": "Payment Gateway Updated Successfully",
  "data": {
        "ID": "65c314574bea7be0c0405e1d",
        "Code": "BNL001",
        "Credential": {
            "merchant_key": "",
            "public_key": ""
        },
        "ClientId": "657f8ed390f51b5bb9be1a38"
    }
}

Error Codes

Error Code	Message	Description
401	Unauthorized	The client token was invalid
400	Validation failed	Inputs are failing validation. The errors field contains details about which fields are violating validation.
500	Server went wrong	An internal error occurred

Delete Payment Gateway

DELETE: BASE_URL/api/v1/payment-gateway/{id}

curl --location --request DELETE 'https://payment-hub.bnlstg.com/api/v1/payment-gateway/65852095e257fc413397985c' 
\ --header 'Accept: application/json' 
\ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' 
\ --data ''

Response Parameters

{
  "success": true,
  "message": "Payment Gateway Deleted Successfully",
  "data": null
}

Error Codes

Error Code	Message	Description
401	Unauthorized	The client token was invalid
404	Unable to get payment gateway	Unable to delete the payment gateway due to data not found by id
500	Server went wrong	An internal error occurred

Transactions

The following endpoints include the processes that will be carried out regarding the transaction.

Create Payment Link

POST: BASE_URL/api/v1/transactions

curl --location 'BASE_URL/api/v1/transactions' 
\ --header 'Content-Type: application/json' 
\ --header 'Accept: application/json' 
\ --header 'Authorization: Bearer eIpprkXsrmnkX5HsGQVtPkBqIeAafpbyY9vC4aCK' 
\ --data-raw '
{
  "merchant_ref_code": "84b88501",
  "amount": 5000000,
  "service_charge": 2500,
  "description": "Booking Invoice",
  "first_name": "Jhon",
  "last_name": "Doe",
  "mobile": "",
  "email": "test@payhub.com",
  "currency": "IDR",
  "payment_vendor": "65f3b208559e33aa146f7dca",
  "payment_method": "",
  "lang": "en",
  "send_email" : true,
  "enable_3d_secure" : true,
  "payment_link_type" : "direct",
  "webhook_url": "https://clientpage.io/webhook/84b88501",
  "success_redirect_url": "https://clientpage.io/transaction/84b88501/success",
  "failed_redirect_url": "https://clientpage.io/transaction/84b88501/failed",
  "cancel_redirect_url": "https://clientpage.io/transaction/84b88501/cancel",
  "expires_in_minutes": 1440,
  "link_expires_in_minutes": 1440
}'

Body Parameters

Field	Descriptions	type
merchant_ref_code	This is likely a reference code or identifier assigned by the merchant to uniquely identify a particular transaction. It helps in tracking and managing transactions.	mandatory \| unique
amount	Represents the monetary value of the transaction, indicating the total amount involved in the payment.	mandatory \| decimal
service_charge	Refers to any additional charges or fees associated with the service. This could include transaction fees or service charges imposed by the payment processing system.	mandatory \| decimal
description	Provides a brief description or comment related to the transaction. It could include details about the purpose of the payment or any other relevant information.	mandatory \| text
first_name	Typically the first name of the person involved in the transaction. This could be the first name of the payer or recipient, depending on the context.	optional \| text
last_name	Typically the last name of the person involved in the transaction. This could be the first name of the payer or recipient, depending on the context.	optional \| text
mobile	Represents the mobile phone number associated with the transaction. It might be used for notifications or communication related to the payment.	optional \| text
email	The email address associated with the transaction. Similar to the mobile number, it could be used for communication and transaction-related notifications.	conditional \| text Note: required for Stripe and Reddot
currency	Indicates the currency in which the transaction is conducted. It specifies the monetary unit, such as USD (U.S. Dollar) or EUR (Euro). Each payment merchant has available currency. To get the available currency, you can check based on Vendor Payment Gateway you used on this transaction.	mandatory \| text
payment_vendor	Refers to the payment service provider or vendor handling the transaction. Fill with your payment gateway ID.	mandatory \| text
payment_method	Referring payment methods that can be used by customers in the payment process. By default, it will use all payment methods available from the relevant payment merchant. Each payment merchant has available payment method. See Vendor Payment Gateway to get list available payment method by Vendor. You can use multi payment method by using array of string on your payload.	optional \| array
lang	Represents the language used in the payment link that will be created at the payment vendor. By default, the language used is English. The available languages are adjusted according to the payment vendor used, along with the languages available for each existing payment vendor. You can refer to Vendor Payment Gateway to get available lang from each Vendor.	optional \| text
send_email	Indicate whether this payment link will be sent to the customer via email or not	bool
enable_3d_secure	Indicate whether to activate 3d secure for payments via Credit Card. This only applies to Xendit and Stripe and will be ignored if you choose payment other than credit card.	bool
payment_link_type	Indicate the type of payment link you will create. There are 2 options, namely "direct" or "invoice". This column only applies to Reddot, and will be ignored for other Vendors.	conditional \| text
webhook_url *	A URL provided by the merchant where real-time updates or notifications about the transaction status can be sent. Webhooks are often used for automated communication. Once transaction has an update on payment status, Payment Hub will send a signal to this Webhook. You can provide the `merchant_ref_code` to this webhook URL parameter. When this webhook is called, you can retrieve the transaction status based on `merchant_ref_code` to get the latest transaction status.	optional \| text \| GET
success_redirect_url	The URL to redirect the user to after a successful transaction. Typically, this is a page confirming the success of the payment.	mandatory \| text
failed_redirect_url	The URL to redirect the user to in case the transaction fails for some reason. It could display an error message or instructions on what to do next.	mandatory \| text
cancel_redirect_url	The URL to redirect the user to if they choose to cancel the transaction before completion.	mandatory \| text
expires_in_minutes	Specifies the time duration, in minutes, within which the transaction needs to be completed. After this period, the transaction may expire.	mandatory \| intenger
link_expires_in_minutes	Similar to expires_in_minutes, but specifically for links associated with the transaction. This could be a link sent to the user for initiating or completing the payment.	mandatory \| intenger

Response Parameters

{
  "message": "Successfully initialized transaction.",
  "data": {
    "payment_url": "https://payment-gateway-provider-domain.com/ASD123QWE346ZXC"
  },
  "success": true
}

Field	Descriptions	type
payment_url	Indicates the URL of the payment vendor to embed in your application, which is used to make invoice payments. This URL can be embedded using an iframe on the website. However, if the payment gateway used is `Stripe`, this URL must be opened directly in the client browser	text

Error Codes

Error Code	Message	Description
401	Unauthorized	The client token was invalid
400	Validation failed	Inputs are failing validation. The errors field contains details about which fields are violating validation.
500	Server went wrong	An internal error occurred

Check Single Transaction

GET: BASE_URL/api/v1/transactions/{merchant_ref_code}

curl --location 'BASE_URL/api/v1/transactions/84b88501' 
\ --header 'Content-Type: application/json' 
\ --header 'Accept: application/json' 
\ --header 'Authorization: Bearer eIpprkXsrmnkX5HsGQVtPkBqIeAafpbyY9vC4aCK'</code>

Response Parameters

{
  "data": {
    "ID": "656d96e92f42c9a894ceb1bb",
    "ClientId": "655fec6e1c3e6572ebebb5cf",
    "Description": "Booking Invoice",
    "FirstName": "Jhon",
    "LastName": "Doe",
    "Amount": 5000000,
    "ServiceCharge": 2500,
    "Mobile": "+81234567890",
    "Currency": "IDR",
    "Email": "test@payhub.com",
    "PaymentMethod": "",
    "PaymentVendor": "65f3b208559e33aa146f7dca",
    "Status": "initial",
    "Total": 390000,
    "MerchantRefCode": "84b88501",
    "WebhookUrl": "https://clientpage.io/webhook/84b88501",
    "PaymentFailReason": "",
    "Lang": "EN",
    "ExpiredAt": "2023-12-04T09:22:53.393Z",
    "CreatedAt": "2023-12-04T09:07:53.393Z",
    "UpdatedAt": null,
    "DeletedAt": null,
    "VendorId": "656d96ea0656f30015614e34",
    "VendorOrderId": "",
    "VendorPaymentId": "",
    "VendorPaidAt": null,
    "VendorPaymentChannel": "",
    "VendorPaymentMethod": "",
    "Refunds": null
  },
  "message": "Success.",
  "success": true
}

Field	Descriptions	type
ClientId	A unique identifier assigned to a client or user. This could be used to track and manage client-specific information in a system.	text
Description	A field providing a brief description or comment related to a particular entity or transaction. It could include details about the nature of the client, the purpose of a payment, or any other relevant information.	text
FirstName	Represents the first name of an individual. It is commonly used for personalization and identification purposes.	text
LastName	Represents the last name of an individual. It, along with the first name, helps uniquely identify a person.	text
Amount	Represents the monetary value associated with a transaction or payment. It indicates the total amount involved.	decimal
ServiceCharge	Indicates any additional charges or fees associated with a service or transaction. This could include processing fees or service charges.	decimal
Mobile	Represents the mobile phone number associated with a client or user. It could be used for communication or verification purposes.	text
Currency	Specifies the currency in which a transaction is conducted, indicating the monetary unit (e.g., USD, EUR).	text
Email	Represents the email address associated with a client or user. It is often used for communication and notifications.	text
PaymentMethod	Describes the method used for making a payment, such as credit card, bank transfer, or other payment options.	text
PaymentVendor	Refers to the vendor or payment service provider involved in processing the payment.	text
Status	Represents the current status of a transaction or entity, indicating whether it's pending, completed, or has encountered an issue. The status of transaction can be: `initial`, Is the default status which indicates that a transaction has just been created and the payment process has not yet been carried out`paid`, Indicates that the transaction has been paid`expired`, Indicates that the transaction has expired or canceled`pending refund`, Indicates that there is a request for a refund on the transaction`partial refund`, Indicates that the refund has been received, with the refund amount being less than the total transaction amount`full refund`, Indicates that the refund has been received, with the refund amount equal to the total transaction amount
Total	Represents the total amount, including both the main amount and any associated service charges.	decimal
MerchantRefCode	A reference code or identifier is assigned by the merchant to uniquely identify a specific transaction.	text
WebhookUrl	A URL where real-time updates or notifications about a transaction can be sent using webhooks.	text
PaymentFailReason	Error message from the payment gateway if it fails to create an invoice. This column will be left empty by default.	text
Lang	Language code used in the payment link or invoice file	text
ExpiredAt	Specifies the expiration time or date associated with a transaction or entity.	DateTime
CreatedAt	Indicates the date and time when a particular entity or transaction was created or initiated.	DateTime
UpdatedAt	Indicates the date and time when a particular entity or transaction was last updated.	DateTime
DeletedAt	Indicates the date and time when a particular entity or transaction was deleted. This is often used in systems that implement soft deletion.	DateTime
VendorId	An identifier associated with a vendor or external entity involved in the transaction.	text
VendorOrderId	Other identifier associated with a vendor. This value will be filled if you use Reddot and LinePay only.	text
VendorPaymentId	A unique identifier is assigned by the vendor to track their side of the payment transaction. This field will be left `null` if the transaction is not paid, and will be filled on the transaction that was paid.	text
VendorPaidAt	Indicates the date and time when the vendor processed or completed their part of the payment.	DateTime
VendorPaymentChannel	Describes the channel or method used by the vendor for payment.	text
VendorPaymentMethod	Describes the payment method used by the vendor.	text
Refunds	An identifier is associated with the vendor when processing a refund. By default, the refund will left `null`	array

Refunds from transaction data will consist of an array indicating that in one transaction several refund stages can be carried out, as long as the cumulative refund does not exceed the total transaction amount. The refund data will consist of several fields.

Field	Description	Type
Number	Describe the steps of a refund	int
SendDate	Indicates the date when a refund was initiated.	DateTime
Reason	Describes the reason for initiating a refund.	text
Amount	Represents the amount involved in a refund transaction.	decimal
ApprovedDate	Indicates the date when a refund was approved.	DateTime
VendorId	An identifier associated with a vendor or external entity involved in the refund process.	text
Status	Represents the current status of a transaction or entity. Status can be `pending refund` , `failed refund`, or `success refund`	text

Error Codes

Error Code	Message	Description
401	Unauthorized	The client token was invalid
404	Unable to get transaction	Could not find the invoice by `merchant_ref_code`
500	Server went wrong	An internal error occurred

Check Bulk Transaction

POST: BASE_URL/api/v1/transactions/fetch-multiple

curl --location 'BASE_URL/api/v1/transactions/fetch-multiple' 
\ --header 'Content-Type: application/json' 
\ --header 'Accept: application/json' 
\ --header 'Authorization: Bearer eIpprkXsrmnkX5HsGQVtPkBqIeAafpbyY9vC4aCK' 
\ --data '{ "merchant_ref_code": [ "ABC11111", "ABC11112", "ABC11113" ] }'

Body Parameters

Field	Descriptions	type
merchant_ref_code	is an array of strings that contains a list of transactions that you will check en masse.	array

Response Parameters

{
  "success": true,
  "message": "Success.",
  "data": [
    {
      "ID": "657f98b146d9ec733c828a7b",
      "ClientId": "657f8ed390f51b5bb9be1a38",
      "Description": "Invoice for #postmana-1235",
      "FirstName": "jhon doe",
      "LastName": "aja",
      "Amount": 50000,
      "ServiceCharge": 3,
      "Mobile": "",
      "Currency": "IDR",
      "Email": "jhon@example.com",
      "PaymentMethod": "",
      "PaymentVendor": "65f3b208559e33aa146f7dca",
      "Status": "success refund",
      "Total": 50003,
      "MerchantRefCode": "ABC11111",
      "WebhookUrl": "https://payku.com/hook/payment/postmana-1234",
      "PaymentFailReason": "",
      "Lang": "EN",
      "ExpiredAt": "2023-12-19T00:56:17.836Z",
      "CreatedAt": "2023-12-18T00:56:17.836Z",
      "UpdatedAt": "2023-12-18T01:05:12.905Z",
      "VendorId": "657f98b3161445f61a7a1fd0",
      "VendorPaymentId": "ddpy-dc6a5595-1c75-4d9e-8788-eb7b39d04c5b",
      "VendorPaidAt": "2023-12-18T00:58:01.773Z",
      "VendorPaymentChannel": "DD_MANDIRI",
      "VendorPaymentMethod": "DIRECT_DEBIT",
      "Refunds": null
    },
    {
      "ID": "657fd5541b55c8927ecb2899",
      "ClientId": "657f8ed390f51b5bb9be1a38",
      "Description": "Invoice for #PH-6",
      "FirstName": "via",
      "LastName": "doe",
      "Amount": 50000,
      "ServiceCharge": 3,
      "Mobile": "",
      "Currency": "IDR",
      "Email": "via@example.com",
      "PaymentMethod": "",
      "PaymentVendor": "65f3b208559e33aa146f7dca",
      "Status": "partial refund",
      "Total": 50003,
      "MerchantRefCode": "ABC11112",
      "WebhookUrl": "https://payku.com/hook/payment/ABC11112",
      "PaymentFailReason": "",
      "Lang": "EN",
      "ExpiredAt": "2023-12-19T05:15:00.605Z",
      "CreatedAt": "2023-12-18T05:15:00.605Z",
      "UpdatedAt": "2023-12-18T05:15:19.514Z",
      "VendorId": "657fd556a4ef048d8f94dea9",
      "VendorPaymentId": "ewc_7de185f3-354c-4f35-9201-3cab92ad9260",
      "VendorPaidAt": "2023-12-18T05:15:15.708Z",
      "VendorPaymentChannel": "SHOPEEPAY",
      "VendorPaymentMethod": "EWALLET",
      "Refunds": [
        {
          "Number": 1,
          "SendDate": "2023-12-18T05:15:51.191Z",
          "Reason": "Cancel Booking",
          "Amount": 20000,
          "ApprovedDate": "2023-12-18T05:15:56.652757Z",
          "VendorID": "ewr_c43619ff-ee23-4bd5-9e5c-5cf9ab880b0a",
          "Status": "success refund"
        }
      ]
    }
  ]
}

Error Codes

Error Code	Message	Description
401	Unauthorized	The client token was invalid
400	Validation failed	Inputs are failing validation. The errors field contains details about which fields are violating validation.
500	Server went wrong	An internal error occurred

Request Refund

POST: BASE_URL/api/v1/transactions/refund

Full Refund

curl --location 'BASE_URL/api/v1/transactions/refund' 
\ --header 'Content-Type: application/json' 
\ --header 'Accept: application/json' 
\ --header 'Authorization: Bearer eIpprkXsrmnkX5HsGQVtPkBqIeAafpbyY9vC4aCK' 
\ --data '{ "merchant_ref_code": "ABC11111", "reason": "cancel booking" }'

Partial Refund

curl --location 'BASE_URL/api/v1/transactions/refund' 
\ --header 'Content-Type: application/json' 
\ --header 'Accept: application/json' 
\ --header 'Authorization: Bearer eIpprkXsrmnkX5HsGQVtPkBqIeAafpbyY9vC4aCK' 
\ --data '{ "merchant_ref_code": "ABC11111", "amount":5000, "reason": "cancel booking", }'

Body Parameters

Field	Descriptions	type
merchant_ref_code	This is likely a reference code or identifier assigned by the merchant to uniquely identify a particular transaction. It helps in tracking and managing transactions.	mandatory
amount *	Represents the monetary value associated with a transaction or payment. It indicates the total amount involved. The system allows a full refundable or partial refundable needs to provide the amount but for a full refund it is optional.	optional \| decimal
reason	The reason field likely holds information about the reason or purpose for initiating a refund. This could include a description of why a refund is being processed, such as product dissatisfaction, service issues, or other specific reasons provided by the client or user.	mandatory

Response Parameters

{
  "message": "Successfully initialized refund.refund take proccess 7 days working day",
  "success": true,
  "data": {
    "merchant_ref_code": "ABC000008",
    "amount": 25000,
    "created_at": "2023-11-28T08:35:18.787Z",
    "payment_method": "E-WALLET",
    "service_charge": 0,
    "status": "pending refund",
    "total": 25000
  }
}

Field	Descriptions	type
merchant_ref_code	This is likely a reference code or identifier assigned by the merchant to uniquely identify a particular transaction. It helps in tracking and managing transactions.	mandatory
amount	Represents the amount of refund request.	optional \| decimal
created_at	Indicates the date when a refund was initiated.	DateTime
payment_method	Describes the payment method used by the vendor.	text
service_charge	Refers to any additional charges or fees associated with the service. This could include transaction fees or service charges imposed by the payment processing system.	decimal
status	Represents the current status of the refund request. The status of the refund can be: `pending refund`, Is the default refund status when the refund is initiated `success refund`, Indicates that the refund has been received.	text
total	Represents the total amount, including both the main amount and any associated service charges.	decimal

Error Codes

Error Code	Message	Description
401	Unauthorized	The client token was invalid
400	Validation failed	Inputs are failing validation. The errors field contains details about which fields are violating validation.
400	The refund amount must not be greater than Transaction's remaining amount	Indicate that the refund amount you requested is greater than the transaction amount or the transaction remaining amount
400	Only PAID or Partial Refund transaction can be refund	Transactions that can be refunded are only transactions with `paid` or `partial refund` status. If you want to make a partial refund, but the status is still `pending refund`, you can make a refund again if the refund process is successful
404	Unable to get transaction	Could not find the invoice by `merchant_ref_code`
500	Server went wrong	An internal error occurred

Cancel Payment Link

POST: BASE_URL/api/v1/transactions/:merchant_ref_code/cancel

curl --location --request POST 'BASE_URL/api/v1/transactions/postmana-1237/cancel' 
\ --header 'Accept: application/json' 
\ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9'

Response Parameters

{
  "success": true,
  "message": "Invoice canceled",
  "data": {
    "ID": "657c01ca001d9c24eb650484",
    "ClientId": "657bf0b3058b4a59138ce273",
    "Description": "Invoice for #postmana-1234",
    "FirstName": "Jhon",
    "LastName": "Doe",
    "Amount": 50000,
    "ServiceCharge": 3,
    "Mobile": "",
    "Currency": "IDR",
    "Email": "jhon@example.com",
    "PaymentMethod": "",
    "PaymentVendor": "65f3b208559e33aa146f7dca",
    "Status": "expired",
    "Total": 50003,
    "MerchantRefCode": "postmana-1237",
    "WebhookUrl": "https://payku.com/hook/payment/postmana-1234",
    "PaymentFailReason": "",
    "Lang": "EN",
    "ExpiredAt": "2023-12-16T07:35:38.546Z",
    "CreatedAt": "2023-12-15T07:35:38.546Z",
    "UpdatedAt": null,
    "VendorId": "657c01ca1614450d427650a3",
    "VendorPaymentId": "",
    "VendorPaidAt": null,
    "VendorPaymentChannel": "",
    "VendorPaymentMethod": "",
    "RefundVendorId": "",
    "RefundSendDate": null,
    "RefundReason": "",
    "RefundTotal": 0,
    "RefundApprovedDate": null
  }
}

Error Codes

Error Code	Message	Description
401	Unauthorized	The client token was invalid
400	Only Initial Transaction can be Canceled	Indicates that the transaction you want to cancel cannot be processed. Transactions that can be canceled are only transactions with `initial` status
404	Unable to get transaction	Could not find the invoice by `merchant_ref_code`
500	Server went wrong	An internal error occurred

Transaction Error Log

This endpoint can be used to view a list of error logs that occur during the create, refund or payment transaction process. You can filter the data that will be displayed using the payload according to the following example.

POST: BASE_URL/api/v1/transactions/log?page=1

curl --location 'BASE_URL/api/v1/transactions/log?page=' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
--header 'Content-Type: application/json' \
--data '{
    "service_name" : "",
    "action_name" : "",
    "metadata" : {
        "merchant_ref_code" : "",
        "transaction_id" : "",
        "token" : ""
    }
}'

Or you can also filter the data according to the following payload as well.

POST: BASE_URL/api/v1/transactions/log?page=1

curl --location 'BASE_URL/api/v1/transactions/log?page=' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
--header 'Content-Type: application/json' \
--data '{
    "service_name" : "Reddot",
    "action_name" : "Create invoice",
    "metadata" : {
        "merchant_ref_code" : "test_testing03",
        "transaction_id" : "665d12f7d06d1405a445d7da",
        "token" : ""
    }
}'

Field	Descriptions	type
service_name	Payment gateway name that was used on transaction log	optional \| string
action_name	Represents the action name based on that error log. Possible value is : create invoice, check transaction, cancel transaction, validate token, create token, charge, create refund, check refund, invoice payment failed, invoice payment cancelled, update customer, create customer, add invoice item, and finalize.	optional \| string
metadata.merchant_ref_code	Indicates the merchant ref code of the transaction that is experiencing an error	optional \| string
metadata.transaction_id	Indicates the transaction ID of the transaction that experienced an error	optional \| text
metadata.token	Indicates the credit card token of the transaction that experienced an error. The value of the token will only be filled if the error originates from the process of charging or validating the credit card token.	optional \| string

Response Parameters

{
    "success": true,
    "message": "Success.",
    "data": [
        {
            "ID": "665d130bd06d1405a445d7dd",
            "ClientId": "65f14d79efc850b3546384e7",
            "LogLevel": "error",
            "ServiceName": "Reddot",
            "ServiceEndpoint": "https://secure-dev.reddotpayment.com/service/payment-api",
            "ActionName": "create invoice",
            "HttpCode": 200,
            "ErrorCode": "-1911",
            "ErrorMessage": "The ccy is not supported or invalid, it must be in ISO-4217 alphabetical format in uppercase letters. Please contact us for further enquiries",
            "RequestPayload": "{\"amount\":56000,\"api_mode\":\"redirection_hosted\",\"back_url\":\"https://payment-hub.bnlstg.com/redirect/callback/665d130bd06d1405a445d7dc/cancel\",\"ccy\":\"BHT\",\"locale\":\"en\",\"merchant_reference\":\"Invoice test_testing03\",\"notify_url\":\"https://payment-hub.bnlstg.com/api/v1/hook/reddot/direct/notify\",\"order_id\":\"test_testing03\",\"payer_email\":\"nana@bookandlink.com\",\"payment_type\":\"S\",\"redirect_url\":\"https://payment-hub.bnlstg.com/redirect/callback/665d130bd06d1405a445d7dc/success\"}",
            "ResponsePayload": "{\"response_status\":\"error\",\"response_code\":\"-1911\",\"response_msg\":\"The ccy is not supported or invalid, it must be in ISO-4217 alphabetical format in uppercase letters. Please contact us for further enquiries\"}",
            "Metadata": [
                {
                    "Key": "transaction_id",
                    "Value": "665d130bd06d1405a445d7dc"
                },
                {
                    "Key": "merchant_ref_code",
                    "Value": "test_testing03"
                }
            ],
            "CreatedAt": "2024-06-03T00:49:15.65Z"
        },
        {
            "ID": "665d12f7d06d1405a445d7db",
            "ClientId": "65f14d79efc850b3546384e7",
            "LogLevel": "error",
            "ServiceName": "Reddot",
            "ServiceEndpoint": "https://secure-dev.reddotpayment.com/service/payment-api",
            "ActionName": "create invoice",
            "HttpCode": 200,
            "ErrorCode": "-1911",
            "ErrorMessage": "The ccy is not supported or invalid, it must be in ISO-4217 alphabetical format in uppercase letters. Please contact us for further enquiries",
            "RequestPayload": "{\"amount\":56000,\"api_mode\":\"redirection_hosted\",\"back_url\":\"https://payment-hub.bnlstg.com/redirect/callback/665d12f7d06d1405a445d7da/cancel\",\"ccy\":\"TBH\",\"locale\":\"en\",\"merchant_reference\":\"Invoice test_testing03\",\"notify_url\":\"https://payment-hub.bnlstg.com/api/v1/hook/reddot/direct/notify\",\"order_id\":\"test_testing03\",\"payer_email\":\"nana@bookandlink.com\",\"payment_type\":\"S\",\"redirect_url\":\"https://payment-hub.bnlstg.com/redirect/callback/665d12f7d06d1405a445d7da/success\"}",
            "ResponsePayload": "{\"response_status\":\"error\",\"response_code\":\"-1911\",\"response_msg\":\"The ccy is not supported or invalid, it must be in ISO-4217 alphabetical format in uppercase letters. Please contact us for further enquiries\"}",
            "Metadata": [
                {
                    "Key": "transaction_id",
                    "Value": "665d12f7d06d1405a445d7da"
                },
                {
                    "Key": "merchant_ref_code",
                    "Value": "test_testing03"
                }
            ],
            "CreatedAt": "2024-06-03T00:48:55.551Z"
        }
    ]
}

Error Codes

Error Code	Message	Description
401	Unauthorized	The client token was invalid
500	Server went wrong	An internal error occurred

Tokenize & Charge Credit Card

Tokenize is used to generate tokens based on the user's credit card. Later this token can be used to make payments or charge transactions. For the time being, this feature can only be used at some merchants.

Shared Payment Page

Shared payment page provides an opportunity for clients to use several types of payment gateways in 1 payment link. Shared payment page supports payments via payment link or tokenize.

POST: BASE_URL/api/v1/shared-payment/initialize

curl --location 'https://payment-hub.bnlstg.com/api/v1/shared-payment/initialize' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9xxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "payment_method" : [
        
        {
            "label": "Shopepay",
            "payment_method" : "SHOPEEPAY",
            "payment_vendor" : "66567b349f208886d5c4e769",
            "currency" : "IDR"
        },

        {
            "label" : "Credit Card",
            "payment_method" : "credit_card_tokenize"
        },

        {
            "label": "Other",
            "payment_method" : "",
            "payment_vendor" : "66567b349f208886d5c4e769", 
            "currency" : "IDR"
        }
    ],
    "payment_detail" : {
        "merchant_ref_code": "BOOKING1123",
        "external_id": "123",
        "source_request": "booking",
        "amount": {
            "mcp" : true,
            "founding_currency" : "JPY",
            "value" : 1000,
            "mcp_rate" : [
                {
                    "currency" : "USD",
                    "value" : 6.43
                },
                {
                    "currency" : "TWD",
                    "value" : 210.26
                },
                {
                    "currency" : "IDR",
                    "value" : 104980
                },
                {
                    "currency" : "KRW",
                    "value" : 9204.82
                }
            ]
        },
        "guest_location" : "KR",
        "hotel_location" : "JA",
        "description": "Invoice BOOKING1123",
        "first_name": "John",
        "last_name": "Doe",
        "mobile": "081xxxxxxxxxxx",
        "email": "dev@bookandlink.com",
        "lang": "en",
        "webhook_url": "https://example.com/t",
        "success_redirect_url": "https://example.com/t/BOOKING1123/status?success=true",
        "failed_redirect_url": "https://example.com/t/BOOKING1123/status?failed=true",
        "cancel_redirect_url": "https://example.com/t/BOOKING1123/status?cancel=true",
        "expires_in_minutes": 60
    }
    
}'

Body Parameters

Field	Sub Field	Descriptions	type
payment_method		Contains all payment method option that customer can choose to pay.	array
	label	The label of the payment method that will appear on the client side	string
	payment_method	Describes the payment method used by the vendor. If you want to use payment via card tokenize, you can enter "credit_card_tokenize"	string \| optional
	currency	Currency to be used	string
payment_detail		Contains payment detail from this shared payment link	object
	merchant_ref_code	This is likely a reference code or identifier assigned by the merchant to uniquely identify a particular transaction. It helps in tracking and managing transactions.	string
	external_id	Extra identifier for client	string
	source_request	Provide source of the payment	string
	amount	Contain transaction amount	object
	guest_location	Alpha country code for guest location	string
	hotel_location	Alpha country code for hotel location. it will used to get payment gateway mapping in Payment Hub	string
	first_name	Typically the first name of the person involved in the transaction. This could be the first name of the payer or recipient, depending on the context.	string
	last_name	Typically the last name of the person involved in the transaction. This could be the first name of the payer or recipient, depending on the context.	string
	mobile	Represents the mobile phone number associated with the transaction. It might be used for notifications or communication related to the payment.	string
	email	The email address associated with the transaction. Similar to the mobile number, it could be used for communication and transaction-related notifications.	string
	lang		string
	webhook_url	A URL provided by the merchant where real-time updates or notifications about the transaction status can be sent. Webhooks are often used for automated communication. Once transaction has an update on payment status, Payment Hub will send a signal to this Webhook. You can provide the `merchant_ref_code` to this webhook URL parameter. When this webhook is called, you can retrieve the transaction status based on `merchant_ref_code` to get the latest transaction status.	string
	success_redirect_url	The URL to redirect the user to after a successful transaction. Typically, this is a page confirming the success of the payment.	string
	failed_redirect_url	The URL to redirect the user to in case the transaction fails for some reason. It could display an error message or instructions on what to do next.	string
	cancel_redirect_url	The URL to redirect the user to if they choose to cancel the transaction before completion.	string
	expires_in_minutes	Specifies the time duration, in minutes, within which the transaction needs to be completed. After this period, the transaction may expire.	integer

Response Parameters

{
    "success": true,
    "message": "Payment initialized",
    "data": {
        "payment_link": "https://paymenthub-fe.bnlstg.com/s/679042df469424f968d901ad",
        "shared_payment": {
            "ID": "679042df469424f968d901ad",
            "ClientId": "65f14d79efc850b3546384e7",
            "TransactionId": "000000000000000000000000",
            "PaymentMethod": [
                {
                    "Label": "Shopepay",
                    "PaymentMethod": "SHOPEEPAY",
                    "PaymentVendor": "66567b349f208886d5c4e769",
                    "Currency": "IDR"
                },
                {
                    "Label": "Credit Card",
                    "PaymentMethod": "credit_card_tokenize",
                    "PaymentVendor": "",
                    "Currency": ""
                },
                {
                    "Label": "Other",
                    "PaymentMethod": "",
                    "PaymentVendor": "66567b349f208886d5c4e769",
                    "Currency": "IDR"
                }
            ],
            "PaymentDetail": {
                "MerchantRefCode": "NICEPAYTEST0044",
                "SourceRequest": "booking",
                "ExternalID": "123",
                "Description": "Invoice NICEPAYTEST0044",
                "FirstName": "John",
                "LastName": "Doe",
                "Mobile": "081xxxxxxxxxxx",
                "Email": "dev@bookandlink.com",
                "PaymentMethod": "",
                "PaymentVendor": "",
                "GuestLocation": "KR",
                "HotelLocation": "JA",
                "Amount": {
                    "MCP": true,
                    "FoundingCurrency": "JPY",
                    "Value": 1000,
                    "MCPRate": [
                        {
                            "Currency": "USD",
                            "Value": 6.43
                        },
                        {
                            "Currency": "TWD",
                            "Value": 210.26
                        },
                        {
                            "Currency": "IDR",
                            "Value": 104980
                        },
                        {
                            "Currency": "KRW",
                            "Value": 9204.82
                        }
                    ]
                },
                "Total": 0,
                "Currency": "",
                "Lang": "en",
                "ExpiredAt": "2025-01-22T01:59:11.549Z",
                "WebhookURL": "https://example.com/t",
                "SuccessRedirectURL": "https://example.com/t/NICEPAYTEST0044/status?success=true",
                "FailedRedirectURL": "https://example.com/t/NICEPAYTEST0044/status?failed=true",
                "CancelRedirectURL": "https://example.com/t/NICEPAYTEST0044/status?cancel=true",
                "ExpiredInMinutes": 60
            },
            "VendorPaymentLink": "",
            "Token": "",
            "AuthUrl": "",
            "IsExpired": false,
            "CreatedAt": "2025-01-22T00:59:11.549Z",
            "UpdatedAt": null,
            "Transaction": {
                "ID": "000000000000000000000000",
                "ClientId": "000000000000000000000000",
                "Description": "",
                "FirstName": "",
                "LastName": "",
                "Amount": 0,
                "ServiceCharge": 0,
                "Mobile": "",
                "Currency": "",
                "Email": "",
                "PaymentMethod": null,
                "PaymentVendor": "",
                "Status": "",
                "Total": 0,
                "MerchantRefCode": "",
                "WebhookUrl": "",
                "PaymentFailReason": "",
                "Lang": "",
                "SendEmail": false,
                "Enable3dSecure": false,
                "PaymentLinkType": "",
                "ExpiredAt": "0001-01-01T00:00:00Z",
                "CreatedAt": "0001-01-01T00:00:00Z",
                "UpdatedAt": null,
                "VendorId": "",
                "VendorOrderId": "",
                "VendorPaymentId": "",
                "VendorPaidAt": null,
                "VendorPaymentChannel": "",
                "VendorPaymentMethod": "",
                "Refunds": null
            }
        }
    }
}

Field	Descriptions	type
payment_link	Indicates the URL of the payment vendor to embed in your application, which is used to make invoice payments. This URL can be embedded using an iframe on the website.	string
shared_payment	Represents the detail of shared payment page	object

Error Codes

Error Code	Message	Description
401	Unauthorized	The client token was invalid
400	Validation failed	Inputs are failing validation. The errors field contains details about which fields are violating validation.
500	Server went wrong	An internal error occurred

On this page