# Billing Account API - Complete Payment Method Registration ## 1. API Overview ### Target Coverage
PG Payment Method
Omise [badge:Card,indigo-subtle]
### Purpose [context] 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. [/context] ### Details [table:key-value] | Item | Value | | :-------------- | :--------------------------- | | **API Name** | Complete Payment Method Registration | | **API Path** | /api/v2/payment-methods/{paymentMethodId}/complete | | **API ID** | EBP_API_121 | | **HTTP Method** | [badge:POST,blue,lg] | | **Region** | [badge:Global,green-subtle,lg] | [/table] ## 2. Request Specification ### 2.1 Request Header @@include:common-headers-link.md@@ #### Custom Headers | Field | Details & Description | | :--- | :--- | | x-ebp-context | [type:string] [req:Yes] [desc:The `paymentHeaderContext` value from the 'Create Payment Method API' (EBP_API_120) response must be included in this header.] | ### 2.2 Path Parameters | Field | Details & Description | | :--- | :--- | | paymentMethodId | [type:string] [req:Yes] [desc: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 | [type:string] [req:Yes] [desc:Payment method code] [eg:CARD] | | 0 | paymentInstrumentId | [type:string] [req:Yes] [desc:One-time token ID obtained via PG SDK] | | 0 | paymentInstrumentType | [type:string] [req:Yes] [desc:Type of payment instrument information] [eg:ONE_TIME_TOKEN] | | 0 | paymentMethodContext | [type:string] [req:Yes] [desc:Encrypted context data received from the Register Payment Method API response] | ### 2.4 Request Examples [tabs] [tab:Card Tokenization Completed] ```json { "paymentMethod": "CARD", "paymentInstrumentId": "tok_test_5w6v4d1d4c1...", "paymentInstrumentType": "ONE_TIME_TOKEN", "paymentMethodContext": "eyJhY3Rpb24iOiJUT0tFTklaRV9DQVJEIiwidG9rZW4iOiJ0b2tf..." } ``` [/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:Unique identifier for the payment method] | | 0 | status | [type:string] [req:Yes] [desc:Current status of the payment method] [eg:ACTIVE] | | 0 | pgResponse | [type:object] [req:Optional] [desc:PG response details object] | | 1 | resultCode | [type:string] [req:Optional] [desc:PG's own result code] | | 1 | pgProvider | [type:string] [req:Optional] [desc:PG provider identifier] [eg:OMISE] | | 1 | data | [type:object] [req:Optional] [desc:Detailed PG response data. Varies by PG. Refer to Detailed PG Response Guide below.] | | -1 | instructions | [type:object] [req:Yes] [desc:Instructions for follow-up processing (Process control)] | | 0 | nextStep | [type:string] [req:Yes] [desc:Next action instruction if further authentication is required] [eg:NONE] | | 0 | paymentUrl | [type:string] [req:Optional] [desc:EBP standard URL to redirect the user if further authentication (HPP, etc.) is required.] | | 0 | requiresClientAction | [type:boolean] [req:Yes] [desc:Whether additional client action (HPP redirection, etc.) is required] | | 0 | clientAction | [type:object] [req:Optional] [desc:Additional action instruction object for the client.] | | 1 | type | [type:string] [req:Optional] [desc:Type of client action] [eg:REDIRECT_TO_HPP] | | 1 | pgProvider | [type:string] [req:Optional] [desc:PG provider to handle the action] | | 0 | requiresFollowUpApi | [type:boolean] [req:Yes] [desc:Whether a follow-up API call is required] | | 0 | followUpApi | [type:object] [req:Optional] [desc: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.requiresClientAction` and `instructions.requiresFollowUpApi` are always `false`, and `instructions.nextStep` is always `NONE`). 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 | [type:string] [req:Yes] [desc:Response data type] [eg:OMISE_CARD_CUSTOMER] | | cardId | [type:string] [req:Yes] [desc:PG's card identifier ID (Last 5 characters masked)] | | customerId | [type:string] [req:Yes] [desc:PG's customer identifier ID (Last 5 characters masked)] | | createdAt | [type:string] [req:Yes] [desc:Data creation timestamp] [eg:2026-04-09T14:13:44Z] | ### 3.3 Response Samples #### Success Case: Card Registration Immediately Active ```json { "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 } } ```