Omise

API Payment Hub > Omise

Before you can integrate with Omise, you are expected to have a Omise 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	NO
2	Tokenize credit card	Support 3ds authentification for spesific account
3	Tokenize 3ds credit card	NO

Currency

The following is a list of available currencies supported by the Omise Payment Gateway.

AUD - Australian Dollar
CAD - Canadian Dollar
CHF - Swiss Franc
CNY - Chinese Yuan
DKK - Danish Krone
EUR - Euro (used by the Eurozone countries)
GBP - British Pound Sterling (United Kingdom)
HKD - Hong Kong Dollar (Hong Kong)
JPY - Japanese Yen (Japan)
MYR - Malaysian Ringgit (Malaysia)
SGD - Singapore Dollar (Singapore)
THB - Thai Baht (Thailand)
USD - United States Dollar (United States)

Language

Omise provides a feature to change the language on generated invoices. The following are the languages supported by Omise.

en - English
ja - Japanese
th - Thailand
id - Indonesian

Payment Method

For now, Omise's payment link only provides a payment method in the form of a credit card

Hosted Payment Page

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

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.

The charge process in Omise is divided into two types based on your merchant account: accounts that support 3DS and those that do not. Below is the difference in the flow between these two types of accounts.

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.

For Omise, tokens that have been generated can be use for onetime payment.

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-QUrz8' \
--header 'Content-Type: application/json' \
--data '{
    
    "payment_vendor": "66038f7438972e914ed5da5a",
    "credit_card" : {
        "account_name" : "Test Card",
        "account_number" : "4100000000000100",
        "exp_month" : "08",
        "exp_year" : 2025,
        "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": "66038f7438972e914ed5da5a",
          "credit_card"   : {
            "account_name"  : "Test Card",
            "account_number": "4100000000000100",
            "exp_month"     : "08",
            "exp_year"      : 2025,
            "cvn"           : "123",
            "email" : "dev@bookandlink.com",
            "phone" : "+6281xxxxxxxxxxxx"
          }
        })
      }).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.phone	Customer phone number	text
credit_card.email	Customer email	text

Response Parameters

{
    "success": true,
    "message": "Tokenize successfully",
    "data": {
        "token": "tokn_test_5z7znue4zznpbgcofpr",
        "status": "verified",
        "auth_url": "",
        "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": "66038f7438972e914ed5da5a",
    "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": "OMISE_000124",
        "amount": 1500,
        "service_charge": 0,
        "description": "Invoice OMISE_000124",
        "currency" : "JPY",
        "first_name": "",
        "last_name": "",
        "mobile": "",
        "email": "",
        "send_email" : true,
        "webhook_url": "https://clientpage.io/webhook/84b88501",
        "return_url" : "http://example.com/success"
    }
}'

<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": "66038f7438972e914ed5da5a",
          "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": "OMISE_000124",
            "amount": 1500,
            "service_charge": 0,
            "description": "Invoice OMISE_000124",
            "currency" : "JPY",
            "first_name": "",
            "last_name": "",
            "mobile": "",
            "email": "",
            "send_email" : true,
            "webhook_url": "https://clientpage.io/webhook/84b88501",
            "return_url" : "http://example.com/success"
          }
        })
      }).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
transaction_detail.return_url	A URL provided by the merchant where the page will be redirected after the 3ds secure process finished. This only used if the account support 3ds tokenize.	optional \| text

Response Parameters

{
    "success": true,
    "message": "Tokenize and Charge Successfully",
    "data": {
        "token": "65d419718e2268001799cd87",
        "status": "verified",
        "auth_url" : "https://api.omise.co/payments/paym_test_62eyfj7wdzp60clsp8d/authorize?acs=false",
        "transaction": {
            "ID": "65d4197150dab0e83598a14b",
            "ClientId": "65d2ab05d469920aee62896f",
            "Description": "Invoice 84b88501",
            "FirstName": "",
            "LastName": "",
            "Amount": 100000,
            "ServiceCharge": 0,
            "Mobile": "",
            "Currency": "JPY",
            "Email": "",
            "PaymentMethod": null,
            "PaymentVendor": "65f3b208559e33aa146f7dca",
            "Status": "paid", // can be paid or pending
            "Total": 100000,
            "MerchantRefCode": "OMISE_000124",
            "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
auth_url	If the account support 3ds tokenize, client can be redirected to this URL to verify. The charging process will be completed if the client has verified via the link.	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

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": "66038f7438972e914ed5da5a",
    "token" : "tokn_test_5z7znue4zznpbgcofpr"
}'

Response Parameters

{
    "success": true,
    "message": "Token check result",
    "data": {
        "chargeable": false,
        "description": "Token was already used",
        "status": "used",
        "token": "tokn_test_5z7znue4zznpbgcofpr"
    }
}

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. It can be "review", "verified", "failed", "fraud", "skipped", "skipped", or "used"	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" : "66038f7438972e914ed5da5a",
    "token" : "tokn_test_5z7znue4zznpbgcofpr",
    "transaction_detail" : {
        "merchant_ref_code": "TEST_STG-500000007",
        "amount": 150,
        "service_charge": 0,
        "description": "Invoice TEST_STG-500000007",
        "currency": "JPY",
        "first_name": "",
        "last_name": "",
        "mobile": "",
        "email": "",
        "payment_method" : "",
        "lang": "",
        "send_email" : true,
        "webhook_url": "https://payku.bnlstg.com/hook/payment/TEST_STG-500000007",
        "return_url" : "http://example.com/success"
    }
}'

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",
        "auth_url": "https://api.omise.co/payments/paym_test_62eyfj7wdzp60clsp8d/authorize?acs=false",
        "transaction": {
            "ID": "65d4197150dab0e83598a14b",
            "ClientId": "65d2ab05d469920aee62896f",
            "Description": "Invoice 84b88501",
            "FirstName": "",
            "LastName": "",
            "Amount": 150,
            "ServiceCharge": 0,
            "Mobile": "",
            "Currency": "JPY",
            "Email": "",
            "PaymentMethod": null,
            "PaymentVendor": "65f3b208559e33aa146f7dca",
            "Status": "pending",
            "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
        }
    }
}

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

Webhook

Webhook is used to obtain real-time transaction data when an invoice is paid and refunded.

Adding hooks can be done via the Omise dashboard → https://dashboard.omise.co/v2/settings/webhooks. To implemented Payment Hub Hook, please adding Payment Hub endpoint as invoice paid hook URL.

Webhook Value:

BASE_URL/api/v1/hook/omise

On this page