### Purpose
[context]
This API creates a payment method for reuse. It is designed to securely store tokenized payment method information provided by the user without exposing sensitive data directly. This API aims to provide a convenient and secure payment experience by utilizing saved payment methods in subsequent payment requests.
For detailed Worldpay guidance, refer to: [Worldpay Detailed Guide](/docs/appendix/store-iframe-guide/worldpay)
For detailed Omise guidance, refer to: [Omise Detailed Guide](/docs/appendix/store-iframe-guide/omise)
For detailed Checkout.com guidance, refer to: [Checkout.com Detailed Guide](/docs/appendix/store-iframe-guide/checkout)
[/context]
### Details
[table:key-value]
| Item | Value |
| :-------------- | :--------------------------- |
| **API Name** | Create Payment Method |
| **API Path** | /api/v2/payment-methods |
| **API ID** | EBP_API_120 |
| **HTTP Method** | [badge:POST,blue,lg] |
| **Region** | [badge:Global,green-subtle,lg] |
[/table]
@@include:billing-account-creation.md@@
## 2. Request Specification
### 2.1 Request Header
@@include:common-headers-link.md@@
### 2.2 Request Data Schema
| depth | Field | Details & Description |
|:------|:--------------------|:---------------------------------------------------------------------|
| 0 | userNo | [type-ml:string,500] [req:Yes] [desc:Unique number identifying the user] |
| 0 | email | [type-ml:string,128] [req:Yes] [desc:User's email address] |
| 0 | paymentMethod | [type:string] [req:Yes] [desc:Type of payment method to register] [eg: CARD, DIRECT_DEBIT] |
| 0 | successUrl | [type-ml:string,500] [req:Yes] [desc:URL to redirect after successful registration] |
| 0 | failureUrl | [type-ml:string,500] [req:Yes] [desc:URL to redirect if registration fails] |
| 0 | billingAddress | [type:object] [req:Optional] [desc:Billing address information (mandatory for tax invoice issuance)] |
| 1 | billingEmail | [type-ml:string,128] [req:Optional] [desc:Billing contact email address] |
| 1 | billingLastName | [type-ml:string,100] [req:Conditional] [desc:Billing contact last name (local language)] |
| 1 | billingFirstName | [type-ml:string,100] [req:Conditional] [desc:Billing contact first name (local language)] |
| 1 | billingCountry | [type-ml:string,3] [req:Conditional] [desc:ISO 3166-1 alpha-3 country code] |
| 1 | billingStreet | [type-ml:string,100] [req:Conditional] [desc:Billing street address] |
| 1 | billingAddressLine1 | [type-ml:string,100] [req:Conditional] [desc:Billing address line 1] |
| 1 | billingAddressLine2 | [type-ml:string,100] [req:Optional] [desc:Billing address line 2] |
| 1 | billingCity | [type-ml:string,100] [req:Conditional] [desc:Billing city] |
| 1 | billingPostalCode | [type-ml:string,100] [req:Conditional] [desc:Billing postal code] |
| 1 | billingState | [type-ml:string,100] [req:Conditional] [desc:Billing state/province] |
| 0 | account | [type:object] [req:Optional] [desc:Account owner information] |
| 1 | accountLastName | [type-ml:string,100] [req:Optional] [desc:User's last name (local language)] |
| 1 | accountFirstName | [type-ml:string,100] [req:Optional] [desc:User's first name (local language)] |
| 0 | directDebitType | [type:string] [req:Conditional] [desc:Mandatory when using DIRECT_DEBIT. Refer to [**Direct Debit Information**](#direct-debit-info) below.] |
> **Direct Debit Information (directDebitType)**
>
> When using Thailand direct debit (`DIRECT_DEBIT`), please check the supported bank codes below.
> - **direct_debit_bay** (Krungsri Bank)
> - **direct_debit_kbank** (Kasikorn Bank)
> - **direct_debit_ktb** (Krungthai Bank)
> - **direct_debit_scb** (Siam Commercial Bank)
### 2.3 Request Examples
#### JSON Example
[tabs]
[tab:CARD]
```json
{
"userNo": "AU1234567890",
"userId": "gildong.hong@example.com",
"email": "gildong.hong@example.com",
"paymentMethod": "CARD",
"successUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/worldpay/success",
"failureUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/worldpay/failure"
}
```
[tab:DIRECT_DEBIT]
```json
{
"userNo": "TH1234567890",
"userId": "gildong.hong@example.com",
"email": "gildong.hong@example.com",
"paymentMethod": "DIRECT_DEBIT",
"successUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/omise/success",
"failureUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/omise/failure",
"directDebitType": "direct_debit_bay"
}
```
[/tabs]
## 3. Response Specification
### 3.1 Response Data Schema
#### Response Data Schema
@@include:standard-response.md@@
| -1 | data | [type:object] [req:Yes] [desc:Response data (Business results)] |
| 0 | paymentMethodId | [type:string] [req:Yes] [desc:Registered payment method ID] |
| 0 | orderNo | [type:string] [req:Yes] [desc:Order number] |
| 0 | status | [type:string] [req:Yes] [desc:Payment method status] [eg:ACTION_REQUIRED] |
| 0 | paymentUrl | [type:string] [req:Optional] [desc:The EBP standard URL to redirect the user to if additional authentication (e.g., HPP) is required. Mandatory if `requiresClientAction` is `true`.] |
| 0 | paymentHeaderContext | [type:string] [req:Optional] [desc:Encrypted payment header context issued by EBP. Must be passed as the x-ebp-context header value when calling the 'Complete Payment Method Registration API'.] |
| 0 | pgResponse | [type:object] [req:Optional] [desc:Original PG response object (required for direct action)] |
| 1 | resultCode | [type:string] [req:Optional] [desc:PG response result code] |
| 1 | data | [type:object] [req:Optional] [desc:Detailed PG response data. Varies by PG.] |
| 0 | successUrl | [type-ml:string,500] [req:Optional] [desc:URL to redirect to after successful payment method registration] |
| 0 | failureUrl | [type-ml:string,500] [req:Optional] [desc:URL to redirect to after failed payment method registration] |
| -1 | instructions | [type:object] [req:Yes] [desc:Instructions for follow-up processing (Process control)] |
| 0 | nextStep | [type:string] [req:Yes] [desc:Next step instruction] [eg:CLIENT_ACTION, REDIRECT] |
| 0 | completionMethod | [type:string] [req:Yes] [desc:Final registration completion method for the entire process] [eg:WEBHOOK, API] |
| 0 | requiresClientAction | [type:boolean] [req:Yes] [desc:Whether additional client action (HPP redirection, tokenization, etc.) is required] |
| 0 | clientAction | [type:object] [req:Optional] [desc:Information object for additional client actions. Mandatory if `requiresClientAction` is `true`.] |
| 1 | type | [type:string] [req:Optional] [desc:Client action type] [eg:TOKENIZE_CARD, CREATE_SOURCE] |
| 1 | pgProvider | [type:string] [req:Optional] [desc:The PG provider handling the action] |
| 0 | requiresFollowUpApi | [type:boolean] [req:Yes] [desc:Whether a follow-up API (Finalization API) call is mandatory] |
| 0 | followUpApi | [type:object] [req:Optional] [desc:Information for the follow-up API to be called after the client action. Mandatory if `requiresFollowUpApi` is `true`.] |
| 1 | method | [type:string] [req:Optional] [desc:HTTP method of the follow-up API] [eg:POST] |
| 1 | url | [type:string] [req:Optional] [desc:Call path of the follow-up API] |
| 1 | description | [type:string] [req:Optional] [desc:Additional description of the follow-up API] |
### 3.2 Response Samples
#### Case 1: Worldpay Card Registration (Redirect + Webhook Completion)
This case involves receiving card information through the PG's hosted payment page (HPP). Once the user enters the information, the PG sends a webhook to EBP to finalize the registration.
* **Next Step**: `REDIRECT` (Move to PG HPP)
* **Completion**: `WEBHOOK` (Asynchronous completion via webhook after user authentication)
```json
{
"resultCode": "0",
"message": "SUCCESS",
"requestId": "06EFX0CRR7ME0KCSSTFEEDRDVG",
"timestamp": "2026-01-27T04:39:47.222Z",
"data": {
"paymentMethodId": "3e104ef7b98f4123948a8c248d0da4c5",
"orderNo": "ORD_7202603277730794",
"status": "ACTION_REQUIRED",
"paymentUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/worldpay/wrapping",
"paymentHeaderContext": "eyJhY3Rpb24iOiJSRURJUkVDVF9UT19IUFAiLCJwcm92aWRlciI6IldPUkxEUEFZIiwiY29udGV4dCI6I...",
"pgResponse": {
"resultCode": "PASS",
"data": {
"pgRefId": "3579052412",
"returnUrl": "https://payments-test.worldpay.com/app/hpp/...",
"referenceUrl": "https://payments-test.worldpay.com/app/hpp/..."
}
},
"successUrl": "http:///v2/ebp/test/token/success",
"failureUrl": "http:///v2/ebp/test/token/fail"
},
"instructions": {
"nextStep": "REDIRECT",
"completionMethod": "WEBHOOK",
"requiresClientAction": true,
"clientAction": {
"type": "REDIRECT_TO_HPP",
"pgProvider": "WORLDPAY"
},
"requiresFollowUpApi": false
}
}
```
#### Case 2: Omise Card Registration (Client Action + API Completion)
This case involves the client directly tokenizing card information using the Omise JS SDK. The obtained token is then passed to EBP's registration completion API to finalize the registration.
* **Next Step**: `CLIENT_ACTION` (Requires calling the JS SDK and obtaining a token)
* **Completion**: `API` (Registration is finalized by the API call)
```json
{
"resultCode": "0",
"message": "SUCCESS",
"requestId": "06EFWD32XT8HCBDCYR9RK7R0PC",
"timestamp": "2026-01-27T04:39:50.123Z",
"data": {
"paymentMethodId": "3a9437e612ac4ccb9beaa6585e899321",
"orderNo": "ORD_7202603277730795",
"status": "ACTION_REQUIRED",
"paymentUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/omise/card/wrapping",
"paymentHeaderContext": "eyJhY3Rpb24iOiJUT0tFTklaRV9DQVJEIiwicHJvdmlkZXIiOiJPTUlTRSIsImNvbnRleHQiOiI...",
"pgResponse": {
"resultCode": "SUCCESS",
"data": {
"publicKey": "pkey_test_46lmsec8z06uh..."
}
}
},
"instructions": {
"nextStep": "CLIENT_ACTION",
"completionMethod": "API",
"requiresClientAction": true,
"clientAction": {
"type": "TOKENIZE_CARD",
"pgProvider": "OMISE"
},
"requiresFollowUpApi": true,
"followUpApi": {
"method": "POST",
"url": "/api/v2/payment-methods/3a9437e612ac4ccb9beaa6585e899321/complete",
"description": "After card tokenization, this API must be called to finalize the registration."
}
}
}
```
#### Case 3: Omise Direct Debit Registration (Client Action + Authentication Required)
In this case, the client uses the Omise JS SDK to create a source (SourceId). The user proceeds to bank authentication through the `paymentUrl` provided in the response. Final registration is handled via a webhook after successful authentication.
* **Step 1 (Current API)**: `CLIENT_ACTION` (Obtain SourceId via JS SDK)
* **Step 2 (Authentication)**: Redirect user to the bank's authentication page via `paymentUrl`
* **Final Completion**: `WEBHOOK` (Asynchronously activated via webhook after authentication)
```json
{
"resultCode": "0",
"message": "SUCCESS",
"requestId": "06EP2JWT2DHQEQGBC3W3RRK72W",
"timestamp": "2026-04-06T05:37:22.536Z",
"data": {
"paymentMethodId": "1fc83f065287471987ee754ef01e7d40",
"orderNo": "ORD_7202603277730796",
"status": "ACTION_REQUIRED",
"paymentUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/omise/direct-debit/wrapping",
"paymentHeaderContext": "eyJhY3Rpb24iOiJDUkVBVEVfU09VUkNFIiwicHJvdmlkZXIiOiJPTUlTRSIsImNvbnRleHQiOiI...",
"successUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/omise/success",
"failureUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/omise/failure",
"pgResponse": {
"resultCode": "OK",
"pgProvider": "OMISE",
"data": {
"type": "OMISE_DIRECT_DEBIT",
"linkedAccountId": "lnac_test_679grm7z8axarr41r6m",
"registrationUri": "https://pay.omise.co/registrations/linked_accounts/lnac_test_679grm7z8axarr41r6m/authorize"
}
}
},
"instructions": {
"nextStep": "CLIENT_ACTION",
"completionMethod": "WEBHOOK",
"requiresClientAction": true,
"clientAction": {
"type": "CREATE_SOURCE",
"pgProvider": "OMISE"
},
"requiresFollowUpApi": false
}
}
```