# Purchase API - Payment Creation
## 1. API Overview
### Purpose
[context]
This API creates a formal Payment resource and completes the final authorization and capture process.
It should be called when the `completionMethod` in the **Create Payment Intent** response is `API`. You must provide the encrypted context (`paymentContext`) issued during the Intent stage, along with authentication information (Token, Source, etc.) obtained from the PG.
The mandatory fields `authRequestId` and `authSignature` must be populated with values obtained as follows:
- **Saved Payment Method**: Use the results from the **Payment PIN Verification API**.
- **Other regular payments**: Use the values returned in the **Create Payment Intent API** response (`pgResponse.data`).
[/context]
### Details
[table:key-value]
| Item | Value |
| :-------------- | :---------------------------- |
| **API Name** | Payment Creation |
| **API Path** | /api/v2/payments |
| **API ID** | EBP_API_230 |
| **HTTP Method** | [badge:POST,blue,lg] |
| **Region** | [badge:Global,green-subtle,lg] |
[/table]
## 2. Request Specification
### 2.1 Request Header
| depth | Field | Details & Description |
|:------|:------------------|:----------------------------------------------------------------------------------------------------------------------------------------------|
| 0 | X-EBP-Context | [type:string] [req:Yes] [desc:The encrypted payment context (paymentHeaderContext) value received as a response from the Create Payment Intent API.] |
| 0 | X-Idempotency-Key | [type:string] [req:Yes] [desc:Idempotency key to prevent duplicate processing for identical payment creation requests.] |
### 2.2 Request Data Schema
The request structure is unified for all types of payment instruments.
| depth | Field | Details & Description |
|:------|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------|
| 0 | authRequestId | [type:string] [req:Yes] [desc:A unique identifier issued upon successful authentication or payment preparation. For saved payment methods (SAVED_PAYMENT_METHOD), use the data.requestId value from the 'Payment PIN Verification API'; for others, use the data.pgResponse.data.authRequestId value from the 'Create Payment Intent API'.] |
| 0 | authSignature | [type:string] [req:Yes] [desc:A security signature for the authRequestId. For saved payment methods (SAVED_PAYMENT_METHOD), use the data.signature value from the 'Payment PIN Verification API'; for others, use the data.pgResponse.data.authSignature value from the 'Create Payment Intent API'.] |
| 0 | paymentMethod | [type:string] [req:Yes] [desc:The payment method used (e.g., CARD, DIRECT_DEBIT).] |
| 0 | paymentInstrumentId | [type:string] [req:Yes] [desc:Identifier for the payment instrument. Can be a PG token, source ID, or a saved payment method ID from EBP.] |
| 0 | paymentInstrumentType | [type:string] [req:Yes] [desc:Type of the instrument ID provided.] [eg:ONE_TIME_TOKEN, ONE_TIME_SOURCE, SAVED_PAYMENT_METHOD] |
| 0 | paymentContext | [type:string] [req:Yes] [desc:Encrypted payment context received from the Payment Intent API. Used to restore order and session information.] |
| 0 | initiatedType | [type:string] [req:Optional] [desc:The entity that initiated the transaction (CUSTOMER or MERCHANT).] [eg:CUSTOMER] |
| 0 | billingAddress | [type:object] [req:Optional] [desc:Billing Address information for fraud detection (FDS).] |
| 1 | firstName | [type:string] [req:Optional] [desc:Buyer's first name.] |
| 1 | lastName | [type:string] [req:Optional] [desc:Buyer's last name.] |
| 1 | addressLine1 | [type:string] [req:Yes] [desc:Primary address line.] |
| 1 | addressLine2 | [type:string] [req:Optional] [desc:Supplementary address line.] |
| 1 | city | [type:string] [req:Yes] [desc:City name.] |
| 1 | stateOrProvince | [type:string] [req:Optional] [desc:State or province name.] |
| 1 | postalCode | [type:string] [req:Yes] [desc:Postal code.] |
| 1 | countryCode | [type:string] [req:Yes] [desc:ISO 3166-1 country code.] |
| 1 | phoneNumber | [type:string] [req:Optional] [desc:Contact phone number.] |
### 2.3 Request Examples
#### JSON Example
[tabs]
[tab:One-Time Token]
```json
{
"authRequestId": "06EKTCYP2Q4GP462WH2Q53WQK0",
"authSignature": "srpLIW9X8WbU7ebDix8uZD6jrKo0fNufPmIS643Ie4I=",
"paymentContext": "QfAy+og0Pc7OaUKV92YAcDd+mvVFP+R5/p2YmxXD4TtDWhV/+sootHKD63BwkLf7nPyrkojvOWHLw7QMY1UzpO57dYAJM/XYb6+UrUwvZmUPXkHcF2xSraKOt4tevD48ozwawiXoKmzg9KOQehCDLK0YYhg8yiEtqXAWEcMqpPkqNlT7mnghfWOokCMFmJQGCVP2NIMHFos8AixkMgPadZUjSLdKeFpwIWGB5LnTKZm3wUXfwDzGljYiAX8ZPfo9XNmvkrFpy3RglYqy+l7JLzR84YswVMqP0hxSPC7EfeM1GrSxwcLgBd58S9qWZeYuSn2p0w7rUFgOTLNcZ7HAK9fDw27lzlPfbqPrhL8eNB+tY3Ic8YJG9H2698Jyv2AMxCpY8N+Uu5e3VWtD2Qm17Le0ARN9ntMmKQNsXqo6HU8o2erlwBX5xddWiEPk7YYr624Je34xoxoUkyIbNAu4BA7fP6+0JFUjQsTVsmZ2GdSXysQoXualLIdTtJlqgO1KenftjQx4XfPS3pl4hxP8BV0inoo4DXcgj65YFprd5QBqC0b20efGZQ3O6PykFzDFYXvnCfLmlo6lNKHg6CawAHBK+K7RqZeRuKpH4GfR5nq3A1FqfVYTVivk3ck7JwKESHFARo6O8NLvslQ3WqClXThOKIufTLNa1o9n0L9gjTC2FDRBgPwsxgaZXHtj3Wa3zWQoH46/sAA2z39szJ+I+IgEfsx++wyKigkaDoPlsb5dII/n2ywv6HAd6F6olpLcQvvllwLpXCkB4MmupokUw9TYI1U2gd2FdYGHgFaGGzXgm20FFTbJxu9idsiR7x2G56GegIjhgXgtLzEclt9x7ZRvsOMWXHXGvXrJpSw2RWwfQCGjtUM45wPvgqQp94qMXvd330C7tAmflDeS08G+AT2SI56mG1D1rZoCj3F3sTjcxjmbbYMOuKr7cWiba9F/YeL2ivETNCyVXdnxWcFGaKlEDxyvRd5aFZuYC1OeBNDysWL76ijfDcVTFJeDJLKoeMHJfOHcGP0rUTgQvXKYrUpnO6hA0IYUuajGxLCqHE9OB0re3LNEy2GBvcN5AZyJyLM6QBO8Op//V0DaDEmamO+aQzVfIveXbGpvlVlCTmaP9MYo3TvdxN1qCsGIl0QmKoGNiP/52Abey0QeOMfFq6lEDxyvRd5aFZuYC1OeBNDr93mSDShWnbfrf0iJVfLF20PpLGJtq1A59zxD3B7GeR2Uqr6WreqxoMpEBAAKbLAR2yaDW7unSwYs3IbslqTvwyeIOm8U+/WA+raJB4ewh3Wbp9Mrurq7GaPpHB2RhOrj/S8ej8XD9QYAHnAKKL/PQJVrCzOlGggOqtOyH9t0Ek1QjXEIe+fNuAPbCbXAjw6w+2WOzVencM2MrK0GS8DBiIzOsWkGUVPZnHVS1GT2SU7FmPseKXUAnWQap5wVsDy5F/Xw3B0hFMAZdrSQLN+t",
"paymentMethod": "CARD",
"paymentInstrumentId": "tokn_test_676q2zf3cn4bduksgow",
"paymentInstrumentType": "ONE_TIME_TOKEN",
"initiatedType": "CUSTOMER"
}
```
[tab:One-Time Source : Installment (Thailand)]
```json
{
"authRequestId": "06EN416SD5Y466ST30EPSX84ZM",
"authSignature": "cZ3Ajawgo/08q3hSiWokenzOYOynyH/Y41/Plz/vfMk=",
"paymentContext": "QfAy+og0Pc7OaUKV92YAcCAcQeOjdSsdLDXZxR3Q+fBDWhV/...",
"paymentMethod": "INSTALLMENT",
"paymentInstrumentId": "src_test_678azwyfocdmky7m4am",
"paymentInstrumentType": "ONE_TIME_SOURCE"
}
```
[tab:Saved Method]
```json
{
"authRequestId": "06EDP0W5343S17MGFGESCG0JV0",
"authSignature": "0aOw85SbsSb3Lg8JNzwCwMpo/+gD1qfdej1f5x7knZU=",
"paymentMethod": "CARD",
"paymentInstrumentId": "46ee7bd8331744b5902509c28879ad16",
"paymentInstrumentType": "SAVED_PAYMENT_METHOD",
"paymentContext": "GAkdwQJ8gx5w6IbCtGxTwMp+z1tGd1FFHz/QNhAv...",
"initiatedType": "CUSTOMER"
}
```
[/tabs]
## 3. Response Specification
### 3.1 Response Data Schema
@@include:standard-response.md@@
| -1 | data | [type:object] [req:Yes] [desc:Response data (Business results)] |
| 0 | orderNo | [type:string] [req:Yes] [desc:EBP order number] |
| 0 | paymentUrl | [type:string] [req:Optional] [desc:The URL to redirect the user to if additional authentication (e.g., 3DS) is required. This can be an EBP-provided bridge page or a direct authentication page provided by the PG. Mandatory if `requiresClientAction` is `true`.] |
| 0 | pgResponse | [type:object] [req:Yes] [desc:Additional PG detailed information] |
| 1 | resultCode | [type:string] [req:Yes] [desc:The result code returned by the PG.] |
| 1 | pgProvider | [type:string] [req:Yes] [desc:The name/code of the Payment Gateway.] |
| 1 | data | [type:object] [req:Optional] [desc:Detailed result data from the PG. The internal fields vary depending on the PG. Please refer to the [**Detailed Response Data per PG**](#32-detailed-response-data-pgresponsedata) section below.] |
| -1 | instructions | [type:object] [req:Yes] [desc:Instructions for follow-up processing (Process control)] |
| 0 | status | [type:string] [req:Yes] [desc:The current state of the payment process.] [eg:AUTHORIZED, ACTION_REQUIRED] |
| 0 | requiresClientAction | [type:boolean] [req:Yes] [desc:Whether additional client action (e.g., authentication redirect) is required.] |
| 0 | clientAction | [type:object] [req:Optional] [desc:Instruction object for the additional client action. Mandatory if `requiresClientAction` is `true`.] |
| 1 | type | [type:string] [req:Optional] [desc:The type of client action.] [eg:REDIRECT_TO_HPP] |
| 1 | pgProvider | [type:string] [req:Optional] [desc:The PG provider handling the action.] |
| 1 | method | [type:string] [req:Optional] [desc:The HTTP Method to be used for redirect] [eg:GET, POST] |
| 0 | requiresFollowUpApi | [type:boolean] [req:Yes] [desc:Whether a follow-up API call is mandatory.] |
| 0 | followUpApi | [type:object] [req:Optional] [desc:Information for the follow-up API after client action. Mandatory if `requiresFollowUpApi` is `true`.] |
> **Payment Flow and Field Usage Guide:**
>
> 1. **instructions.status**: Represents the current processing state of the payment. `AUTHORIZED` means the payment is fully successful, while `ACTION_REQUIRED` indicates that an additional authentication step is needed.
> 2. **instructions.requiresClientAction and data.paymentUrl**: Indicates whether the user needs to be redirected for additional authentication. If `requiresClientAction` is `true`, immediately redirect the user to the provided **`paymentUrl`**.
> 3. **paymentUrl details**: This URL includes the payment context and safely connects the user to the PG's authentication screen via an EBP bridge page.
### 3.2 Detailed Response Data (pgResponse.data)
The internal fields of the `pgResponse.data` object are configured differently according to the integrated PG specifications.
#### Omise
| depth | Field | Details & Description |
|:------|:---------------|:--------------------------------------------------------------------------------------|
| -1 | type | [type:string] [req:Yes] [desc:The type value to identify the PG response data structure.] [eg:OMISE_TOKEN, OMISE_SOURCE] |
| -1 | pgTransactionId| [type:string] [req:Yes] [desc:The order reference or transaction ID from the PG.] |
| -1 | amount | [type:number] [req:Yes] [desc:The amount processed by the PG.] |
| -1 | currencyCode | [type:string] [req:Yes] [desc:The currency code used for the transaction.] |
| -1 | chargedAt | [type:string] [req:Yes] [desc:The timestamp of payment completion at the PG.] |
| -1 | authorizeUri | [type:string] [req:Optional] [desc:The original PG authentication URL (e.g., for 3DS).] |
### 3.3 Response Samples
[tabs]
[tab:Card (Omise)]
```json
{
"resultCode": "0",
"message": "SUCCESS",
"requestId": "06EN43NFZ2P3N7MD6M5K1ND2W0",
"timestamp": "2026-04-03T06:36:29.021557700Z",
"data": {
"orderNo": "ORD_7202604037731729",
"paymentUrl": null,
"pgResponse": {
"resultCode": "OK",
"pgProvider": "OMISE",
"data": {
"type": "OMISE_TOKEN",
"pgTransactionId": "chrg_test_678b3p4rhqk7fl2iu71",
"amount": 129,
"currencyCode": "THB",
"chargedAt": "2026-04-02T21:36:28Z",
"authorizeUri": null
}
}
},
"instructions": {
"status": "AUTHORIZED",
"requiresClientAction": false,
"requiresFollowUpApi": false
}
}
```
[tab:Installment (Omise)]
```json
{
"resultCode": "0",
"message": "SUCCESS",
"requestId": "06EN49JGVDMKNQMZXY9QSG8H1M",
"timestamp": "2026-04-03T07:02:17.503946500Z",
"data": {
"orderNo": "ORD_7202604037731753",
"paymentUrl": "https://pay.omise.co/offsites/ofsp_test_678bcs88ibmtqhjzsbs/pay?acs=false",
"pgResponse": {
"resultCode": "OK",
"pgProvider": "OMISE",
"data": {
"type": "OMISE_SOURCE",
"pgTransactionId": "chrg_test_678bcs862cers7axonh",
"amount": 2500.0,
"currencyCode": "THB",
"chargedAt": "2026-04-02T22:02:17Z",
"authorizeUri": "https://pay.omise.co/offsites/ofsp_test_678bcs88ibmtqhjzsbs/pay?acs=false"
}
}
},
"instructions": {
"status": "ACTION_REQUIRED",
"requiresClientAction": true,
"clientAction": {
"type": "REDIRECT_TO_HPP",
"pgProvider": "OMISE",
"method": "GET"
},
"requiresFollowUpApi": false
}
}
```
[tab:BankTransfer (Thailand)]
```json
{
"resultCode": "0",
"message": "SUCCESS",
"requestId": "06EN4A9GAYG551E1KCG5TVB41C",
"timestamp": "2026-04-03T07:05:25.222386700Z",
"data": {
"orderNo": "ORD_7202604037731757",
"paymentUrl": "https://pay.omise.co/payments/pay2_test_678bdvvvi2viwx9kpu6/authorize?acs=false",
"pgResponse": {
"resultCode": "OK",
"pgProvider": "OMISE",
"data": {
"type": "OMISE_SOURCE",
"pgTransactionId": "chrg_test_678bdvvtu4d2cj6xpq1",
"amount": 2500.0,
"currencyCode": "THB",
"chargedAt": "2026-04-02T22:05:24Z",
"authorizeUri": "https://pay.omise.co/payments/pay2_test_678bdvvvi2viwx9kpu6/authorize?acs=false"
}
}
},
"instructions": {
"status": "ACTION_REQUIRED",
"requiresClientAction": true,
"clientAction": {
"type": "REDIRECT_TO_HPP",
"pgProvider": "OMISE",
"method": "GET"
},
"requiresFollowUpApi": false
}
}
```
[/tabs]