Billing Account API - Complete Payment Method Registration #
1. API Overview #
Target Coverage #
| PG | Payment Method |
|---|---|
| Omise | Card |
Purpose #
This API is called when the nextStep field in the 'Create Payment Method' response is CLIENT_ACTION and the completionMethod is API.
Currently, this API call is only required for Card (CARD) registration with Omise PG.
After completing the instructed client action (card tokenization), the resulting token value is sent to the server to finalize the payment method registration.
Details #
| Item | Value |
|---|---|
| API Name | Complete Payment Method Registration |
| API Path | /api/v2/payment-methods/{paymentMethodId}/complete |
| API ID | EBP_API_121 |
| HTTP Method | POST |
| Region | Global |
2. Request Specification #
2.1 Request Header #
For detailed header information, please refer to the Common Headers documentation.
Custom Headers #
| Field | Details & Description |
|---|---|
| x-ebp-context |
🔴 Required The |
2.2 Path Parameters #
| Field | Details & Description |
|---|---|
| paymentMethodId |
🔴 Required The ID of the payment method to complete registration (received from the Register API response) |
2.3 Request Data Schema #
| depth | Field | Details & Description |
|---|---|---|
| 0 | paymentMethod |
🔴 Required Payment method code e.g., CARD |
| 0 | paymentInstrumentId |
🔴 Required One-time token ID obtained via PG SDK |
| 0 | paymentInstrumentType |
🔴 Required Type of payment instrument information e.g., ONE_TIME_TOKEN |
| 0 | paymentMethodContext |
🔴 Required Encrypted context data received from the Register Payment Method API response |
2.4 Request Examples #
{
"paymentMethod": "CARD",
"paymentInstrumentId": "tok_test_5w6v4d1d4c1...",
"paymentInstrumentType": "ONE_TIME_TOKEN",
"paymentMethodContext": "eyJhY3Rpb24iOiJUT0tFTklaRV9DQVJEIiwidG9rZW4iOiJ0b2tf..."
}
3. Response Specification #
3.1 Response Data Schema #
Response Data Schema #
| depth | Field | Details & Description |
|---|---|---|
| -1 | resultCode |
🔴 Required Result code e.g., "0" for success, "EBP-A-0001" for error |
| -1 | message |
🔴 Required Result message |
| -1 | requestId |
🔴 Required Unique request identifier for tracking |
| -1 | timestamp |
🔴 Required Response timestamp in ISO 8601 format e.g., 2025-12-19T14:24:00+09:00 |
| -1 | data |
🔴 Required Response data (Business results) |
| 0 | paymentMethodId |
🔴 Required Unique identifier for the payment method |
| 0 | status |
🔴 Required Current status of the payment method e.g., ACTIVE |
| 0 | pgResponse |
⚪ Optional PG response details object |
| 1 | resultCode |
⚪ Optional PG's own result code |
| 1 | pgProvider |
⚪ Optional PG provider identifier e.g., OMISE |
| 1 | data |
⚪ Optional Detailed PG response data. Varies by PG. Refer to Detailed PG Response Guide below. |
| -1 | instructions |
🔴 Required Instructions for follow-up processing (Process control) |
| 0 | nextStep |
🔴 Required Next action instruction if further authentication is required e.g., NONE |
| 0 | paymentUrl |
⚪ Optional EBP standard URL to redirect the user if further authentication (HPP, etc.) is required. |
| 0 | requiresClientAction |
🔴 Required Whether additional client action (HPP redirection, etc.) is required |
| 0 | clientAction |
⚪ Optional Additional action instruction object for the client. |
| 1 | type |
⚪ Optional Type of client action e.g., REDIRECT_TO_HPP |
| 1 | pgProvider |
⚪ Optional PG provider to handle the action |
| 0 | requiresFollowUpApi |
🔴 Required Whether a follow-up API call is required |
| 0 | followUpApi |
⚪ Optional Information for the follow-up API to be called after the additional action. |
Note: In the current system, there are no cases where additional client actions or follow-up API calls are required after calling this API. (
instructions.requiresClientActionandinstructions.requiresFollowUpApiare alwaysfalse, andinstructions.nextStepis alwaysNONE). However, these fields are included for consistency with other APIs and future extensibility.
3.2 Detailed PG Response (pgResponse) Guide #
The structure of the pgResponse.data object varies depending on the PG provider and payment method.
Omise - Card #
| Field | Details & Description |
|---|---|
| type |
🔴 Required Response data type e.g., OMISE_CARD_CUSTOMER |
| cardId |
🔴 Required PG's card identifier ID (Last 5 characters masked) |
| customerId |
🔴 Required PG's customer identifier ID (Last 5 characters masked) |
| createdAt |
🔴 Required Data creation timestamp e.g., 2026-04-09T14:13:44Z |
3.3 Response Samples #
Success Case: Card Registration Immediately Active #
{
"resultCode": "0",
"message": "SUCCESS",
"requestId": "06EQ59HTGK7KYSEHV68ZZEY1C0",
"timestamp": "2026-04-09T14:29:50.381Z",
"data": {
"paymentMethodId": "7967a291ff954b23acca7e0caeb648b9",
"status": "ACTIVE",
"pgResponse": {
"resultCode": "OK",
"pgProvider": "OMISE",
"data": {
"type": "OMISE_CARD_CUSTOMER",
"cardId": "card_test_67as23ugo5x0of*****",
"customerId": "cust_test_67as22ax1gdv91*****",
"createdAt": "2026-04-09T14:13:44Z"
}
}
},
"instructions": {
"nextStep": "NONE",
"paymentUrl": null,
"requiresClientAction": false,
"requiresFollowUpApi": false
}
}