Kovena

API Payment Hub > Kovena

Before you can integrate with Doku, you are expected to have a Doku account and register your Key on the Payment Hub. See Payment Gateway to register.

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

#	Feature	Support
1	Return to specific URL after success or failed to pay	YES
2	Tokenize credit card	YES
3	Tokenize 3ds credit card	YES

Currency

The currency you can choose depends on your subscription at Kovena.

Language

Kovena does not provide a feature to change the language. By default, the hosted payment page will use English.

Payment Method

The hosted payment page on Kovena only supports credit card payments.

Hosted Payment Page

To create a payment link, kovena has a slightly different payload. Here is an example request to create a kovena payment link.

POST: BASE_URL/api/v1/transactions

curl --location 'BASE_URL/api/v1/transactions' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eIpprkXsrmnkX5HsGQVtPkBqIeAafpbyY9vC4aCK.NPD6Xtaj6bVR3NU-blDdR_W8_P2pP4VNIeJo60lNU0s' \
--header 'Content-Type: application/json' \
--data-raw '{
    "merchant_ref_code": "KOVENA00066",
    "amount": 1500,
    "service_charge": 0,
    "description": "Invoice KOVENA00066",
    "first_name": "John Doe",
    "last_name": "",
    "mobile": "",
    "email": "sparta@bookandlink.com",
    "currency": "VND",
    "payment_vendor": "67a1817f68471dda5f1245dc",
    "payment_method" : "",
    "lang": "",
    "send_email" : true,
    "enable_3d_secure" : false,
    "payment_link_type" : "invoice",
    "webhook_url": "http://example.com",
    "success_redirect_url": "http://example.com/success",
    "failed_redirect_url": "http://example.com/failed",
    "cancel_redirect_url": "http://example.com/cancel",
    "expires_in_minutes": 60,
    "link_expires_in_minutes" : 1,
    "payment_detail" : {
        "guest_location" : "ID",
        "booking_date" : "2025-01-01",
        "check_in_date" : "2025-01-02",
        "check_out_date" : "2025-01-03"
    }
}'

Kovena allows to present hosted payment links via html iframe. Below are several screenshots of the hosted payment link from Kovena.

Tokenize

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.

In Payment Hub, this endpoint can be used specifically to create tokens only, or automatically charge transactions.

We recommend that this process be carried out directly from the client page so that the customer's credit card credentials do not pass through your server. This process can be done with your public token or client token as the Authorization header. For the security of your account, use a public token if this process is done via client side.

Kovena Test Credit Cards

Brand	PAN	CVV	3D Secure 2 Flow	Outcome
	4000001000000042	123	Challenge	Authenticated
	5100001000000022	123	Challenge	Authenticated

Passwords for Challenge Flow

For 3D Secure 2 cards which have a Challenge Flow, use the following passwords when prompted.

Password	Outcome
4444	Authenticated
4009	Declined

Create Token Only

POST: BASE_URL/api/v1/transactions/token

curl --location 'BASE_URL/api/v1/transactions/token' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
--header 'Content-Type: application/json' \
--data '{
    "payment_vendor": "65f3b208559e33aa146f7dca",
    "credit_card" : {
        "account_name" : "John Doe",
        "account_number" : "3530111333300000",
        "exp_month" : "12",
        "exp_year" : 2040,
        "cvn" : "123",
        "email" : "dev@bookandlink.com",
        "phone" : "+6281xxxxxxxxxxxx"
    }
}'

<html>

  <body>
    <button onclick="generateToken()">Generate Token</button>
  </body>

  <script>
    async function generateToken() {
      var   public_key = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9";
      const token      = await fetch('BASE_URL/api/v1/transactions/token', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${public_key}`,
        },
        body: JSON.stringify({
          "payment_vendor": "65f3b208559e33aa146f7dca",
          "credit_card"   : {
            "account_name"  : "Test Card",
            "account_number": "3530111333300000",
            "exp_month"     : "12",
            "exp_year"      : 2040,
            "cvn"           : "123",
            "email" : "dev@bookandlink.com",
            "phone" : "081xxxxxxxxxxxx"
          }
        })
      }).then(r => r.json())
      console.log(token);
    }

  </script>
</html>

Body Parameters

Field	Descriptions	Type
payment_vendor	Your payment gateway ID to use.	text
credit_card.account_name	Customer credit card account name	text
credit_card.account_number	Customer credit card account number	text
credit_card.exp_month	Customer credit card expired account month	text
credit_card.exp_year	Customer credit card expired account year	number
credit_card.cvn	3 digit of credit card CVN	text
credit_card.email	Customer email	text
credit_card.phone	Customer phone number	text

Response Parameters

{
    "success": true,
    "message": "Tokenize successfully",
    "data": {
        "token": "65d41a418e2268001799cda1",
        "status": "verified",
        "transaction": null
    }
}

Create Token & Charge

POST: BASE_URL/api/v1/transactions/token

curl --location 'BASE_URL/api/v1/transactions/token' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
--header 'Content-Type: application/json' \
--data '{
    "payment_vendor": "65f3b208559e33aa146f7dca",
    "credit_card" : {
        "account_name" : "John Doe",
        "account_number" : "4000000000001091",
        "exp_month" : "12",
        "exp_year" : 2040,
        "cvn" : "123",
        "email" : "dev@bookandlink.com",
        "phone" : "+6281xxxxxxxxxxxx"
    }, 
    "transaction_detail" : {
        "merchant_ref_code": "84b88501",
        "amount": 100000,
        "service_charge": 0,
        "description": "Invoice 84b88501",
        "currency" : "IDR",
        "first_name": "",
        "last_name": "",
        "mobile": "",
        "email": "",
        "send_email" : true,
        "webhook_url": "https://clientpage.io/webhook/84b88501"
    }
}'

<html>

  <body>
    <button onclick="generateToken()">Generate Token</button>
  </body>

  <script>
    async function generateToken() {
      var   public_key = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9";
      const token      = await fetch('BASE_URL/api/v1/transactions/token', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${public_key}`,
        },
        body: JSON.stringify({
          "payment_vendor": "65f3b208559e33aa146f7dca",
          "credit_card" : {
            "account_name" : "John Doe",
            "account_number" : "4000000000001091",
            "exp_month" : "12",
            "exp_year" : 2040,
            "cvn" : "123",
            "email" : "dev@bookandlink.com",
            "phone" : "+6281xxxxxxxxxxxx"
          }, 
          "transaction_detail" : {
            "merchant_ref_code": "84b88501",
            "amount": 100000,
            "service_charge": 0,
            "description": "Invoice 84b88501",
            "currency" : "IDR",
            "first_name": "",
            "last_name": "",
            "mobile": "",
            "email": "",
            "send_email" : true,
            "webhook_url": "https://clientpage.io/webhook/84b88501"
          }
        })
      }).then(r => r.json())
      console.log(token);
    }

  </script>
</html>

Body Parameters

Field	Descriptions	Type
payment_vendor	Your payment gateway ID to use	text
credit_card.account_name	Customer credit card account name	text
credit_card.account_number	Customer credit card account number	text
credit_card.exp_month	Customer credit card expired account month	text
credit_card.exp_year	Customer credit card expired account year	number
credit_card.cvn	3 digit of credit card CVN	text
credit_card.email	Customer email	text
credit_card.phone	Customer phone	text
transaction_detail.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
transaction_detail.amount	Represents the monetary value of the transaction, indicating the total amount involved in the payment.	mandatory \| decimal
transaction_detail.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
transaction_detail.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
transaction_detail.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
transaction_detail.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
transaction_detail.mobile	Represents the mobile phone number associated with the transaction. It might be used for notifications or communication related to the payment.	optional \| text
transaction_detail.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
transaction_detail.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
transaction_detail.send_email	Indicate whether this payment link will be sent to the customer via email or not	bool
transaction_detail.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

Response Parameters

{
    "success": true,
    "message": "Tokenize and Charge Successfully",
    "data": {
        "token": "65d419718e2268001799cd87",
        "status": "verified",
        "transaction": {
            "ID": "65d4197150dab0e83598a14b",
            "ClientId": "65d2ab05d469920aee62896f",
            "Description": "Invoice 84b88501",
            "FirstName": "",
            "LastName": "",
            "Amount": 100000,
            "ServiceCharge": 0,
            "Mobile": "",
            "Currency": "IDR",
            "Email": "",
            "PaymentMethod": null,
            "PaymentVendor": "65f3b208559e33aa146f7dca",
            "Status": "paid",
            "Total": 100000,
            "MerchantRefCode": "84b88501",
            "WebhookUrl": "https://clientpage.io/webhook/84b88501",
            "PaymentFailReason": "",
            "Lang": "",
            "SendEmail": true,
            "Enable3dSecure": false,
            "PaymentLinkType": "",
            "ExpiredAt": "0001-01-01T00:00:00Z",
            "CreatedAt": "2024-02-20T03:16:01.184Z",
            "UpdatedAt": "2024-02-20T03:16:05.429Z",
            "VendorId": "",
            "VendorOrderId": "",
            "VendorPaymentId": "65d419756449350015255ab2",
            "VendorPaidAt": "2024-02-20T03:16:05.429Z",
            "VendorPaymentChannel": "VISA",
            "VendorPaymentMethod": "CREDIT_CARD",
            "Refunds": null
        }
    }
}

Field	Descriptions	type
token	Represent the generated token from credit card	text
status	Represent the token status from merchant. It can be "review", "verified", "failed", "fraud", "skipped", "skipped", "used"	text
transaction	Represent the transaction that has been charge. Will return null if create token only	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

Create 3ds Token

This endpoint is specifically used to generate 3D secure tokens. This endpoint will provide the one time use token, status and verify URL.

POST: BASE_URL/api/v1/transactions/token/3ds

Server side example

curl --location 'BASE_URL/api/v1/transactions/token/3ds' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
--header 'Content-Type: application/json' \
--data '{
    
    "payment_vendor": "66021e70b3239bdfc1dcd8e1",
    "credit_card" : {
        "account_name" : "Test Card",
        "account_number" : "4100000000000100",
        "exp_month" : "08",
        "exp_year" : 2025
    },
    "amount"    : 1500000,
    "currency"  : "IDR",
    "return_url" : "https://example.com/complete"

}'

Client Side Example

<html>

  <body>
    <button onclick="generateToken()">Generate Token</button>
  </body>

  <script>
    async function generateToken() {
      var   public_key = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6Ik9iamVjdElEKFwiNjYwMjE4NDBiMzIzOWJkZmMxZGNkOGRiXCIpIiwiR2VuZXJhdGVkQXQiOiIyMDI0LTAzLTI3VDE2OjQzOjE4LjEzOTkwNjYzNiswODowMCIsIlRva2VuVHlwZSI6InB1YmxpYyIsImV4cCI6MTcxMTUzMjU5OH0.sfw-Jg9OcL443VU4q1AXlYE2l8o3aqnHKneCA-xWVLM";
      const token      = await fetch('BASE_URL/api/v1/transactions/token/3ds', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${public_key}`,
        },
        body: JSON.stringify({
          "payment_vendor": "66021e70b3239bdfc1dcd8e1",
          "credit_card"   : {
            "account_name"  : "Test Card",
            "account_number": "4100000000000100",
            "exp_month"     : "08",
            "exp_year"      : 2025,
            "cvn"           : "123"
          },
          "amount"    : 1500000,
          "currency"  : "IDR",
          "return_url": "https://example.com/complete"
        })
      }).then(r => r.json())
      console.log(token);
    }

  </script>
</html>

Body Parameters

Field	Descriptions	Type
payment_vendor	Your payment gateway ID to use	text
credit_card.account_name	Customer credit card account name	text
credit_card.account_number	Customer credit card account number	text
credit_card.exp_month	Customer credit card expired account month	text
credit_card.exp_year	Customer credit card expired account year	number
credit_card.cvn	3 digit of credit card CVN. It won't be used for domestic Korean cards	text
amount	Amount to charge	number
currency	Indicates the currency in which the transaction is conducted.	text
return_url	The URL to redirect the user to after a user successfully verify their credit card token	text

Response Parameters

{
    "success": true,
    "message": "Tokenize successfully",
    "data": {
        "token": "JFRO2aWAzFZtGM30nzCqlcqeStAmPR6iigd4zEHfyJU1O1pzRzrqqTXerKEKjEGBWhwn-FObAqmzvMyJMIP01FUbKqeuC0WJFmsoGyNP_TDcjCZN",
        "status": "verified",
        "auth_url": "https://sandbox.doku.com/wt-frontend-transaction/three-d-secure?authenticationId=c94b6e55f229f3ba88a6cc987e0690e8fe344ce72cf9498f54cad1cf6311869e&clientId=BRN-0268-1732755484580"
    }
}

Field	Descriptions	type
token	Represent the generated token from credit card	text
status	Represent the token status from merchant. For Doku, this status will always "verify"	text
auth_url	Client can be redirected to this URL to verify the token before charge.	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 Token Status

This endpoint allow you to check the status of token.

GET: BASE_URL/api/v1/transactions/token

curl --location --request GET 'BASE_URL/api/v1/transactions/token' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.GV-Wei86FcFsdWz8wXMgzyBx06zaQLAUTMK4k-QUrz8' \
--header 'Content-Type: application/json' \
--data '{
    "payment_vendor": "65f3eadc9d311dea1a9f1ff8",
    "token" : "MFe0Rw-dpMp6eJwqf045bOR3WJpIPj6ix9mzeCT7bGKfuN0htGjynvOi_yp6rVrKvSnpJAOZ-hDLK4ZwrM0mWTo6b1cyrwVqrvVq4lxMbqY6cfUo"
}'

Response Parameters

{
    "success": true,
    "message": "Token check result",
    "data": {
        "chargeable": true,
        "description": "",
        "status": "verified",
        "token": "MFe0Rw-dpMp6eJwqf045bOR3WJpIPj6ix9mzeCT7bGKfuN0htGjynvOi_yp6rVrKvSnpJAOZ-hDLK4ZwrM0mWTo6b1cyrwVqrvVq4lxMbqY6cfUo"
    }
}

Field	Descriptions	type
chargeable	Indicate the token is available to charge or not	boolean
description	Indicate the description of token state	text
status	Represent the token status from merchant. For Doku, this status will always "verify"	text
token	Echo back the token from your payload	text

Create Charge

If you don't want to automatically charge generated tokens, you can charge them manually via this endpoint.

POST: BASE_URL/api/v1/transactions/charge

curl --location 'BASE_URL/api/v1/transactions/charge' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
--header 'Content-Type: application/json' \
--data '{
    "payment_vendor" : "65f3eadc9d311dea1a9f1ff8",
    "token" : "MFe0Rw-dpMp6eJwqf045bOR3WJpIPj6ix9mzeCT7bGKfuN0htGjynvOi_yp6rVrKvSnpJAOZ-hDLK4ZwrM0mWTo6b1cyrwVqrvVq4lxMbqY6cfUo",
    "transaction_detail" : {
        "merchant_ref_code": "TEST_STG-500000007",
        "amount": 1500000,
        "service_charge": 0,
        "description": "Invoice TEST_STG-500000007",
        "currency": "IDR",
        "first_name": "",
        "last_name": "",
        "mobile": "",
        "email": "",
        "payment_method" : "",
        "lang": "",
        "send_email" : true,
        "webhook_url": "https://payku.bnlstg.com/hook/payment/TEST_STG-500000007"
    }
}'

Body Parameters

Field	Descriptions	type
payment_vendor	Your payment gateway ID to use	text
token	Credit card token that has been generated from create token endpoint.	text
transaction_detail	Detailed transaction information that you want to charge	object

Response Parameters

This endpoint will create payment to current transaction based on merchant_ref_code and will echo back the paid transaction data.

{
    "success": true,
    "message": "Charge Credit Card Successfully",
    "data": {
        "token": "65d434c1644935001525604c",
        "transaction": {
            "ID": "65d4197150dab0e83598a14b",
            "ClientId": "65d2ab05d469920aee62896f",
            "Description": "Invoice 84b88501",
            "FirstName": "",
            "LastName": "",
            "Amount": 1500,
            "ServiceCharge": 0,
            "Mobile": "",
            "Currency": "IDR",
            "Email": "",
            "PaymentMethod": null,
            "PaymentVendor": "65f3b208559e33aa146f7dca",
            "Status": "paid",
            "Total": 100000,
            "MerchantRefCode": "TEST_STG-500000007",
            "WebhookUrl": "https://clientpage.io/webhook/84b88501",
            "PaymentFailReason": "",
            "Lang": "",
            "SendEmail": true,
            "Enable3dSecure": false,
            "PaymentLinkType": "",
            "ExpiredAt": "0001-01-01T00:00:00Z",
            "CreatedAt": "2024-02-20T03:16:01.184Z",
            "UpdatedAt": "2024-02-20T03:16:05.429Z",
            "VendorId": "",
            "VendorOrderId": "",
            "VendorPaymentId": "65d419756449350015255ab2",
            "VendorPaidAt": "2024-02-20T03:16:05.429Z",
            "VendorPaymentChannel": "VISA",
            "VendorPaymentMethod": "CREDIT_CARD",
            "Refunds": null
        }
    }
}

Note:

Transaction status can be "paid" or "failed".

paid, If the charge process is successful with the token
failed, if the charge process is failed with the token provided

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