Post-authorization maintenance - void/cancel a transaction via cancelTransaction, plus refund and settle operations covered by the payment maintenance guides. JWT request and response signed with the merchant secret key.
openapi: 3.0.3
info:
title: 2C2P Payment Gateway API (PGW v4.3)
description: >-
Server-to-server REST interface for the 2C2P Payment Gateway. Every
operation is an HTTPS POST under /payment/4.3/. IMPORTANT: on the wire, each
request and response body is a single JSON Web Token (JWS) signed with the
merchant's Secret Key using HMAC SHA-256 - the merchant is identified by the
merchantID inside the signed payload, and there is no HTTP Authorization
header. For readability this document models the DECODED JSON payloads
(request `payload` and response `payload`) rather than the raw JWT string.
The field schemas here are MODELED from the documented parameters and are a
representative subset, not a byte-for-byte copy of 2C2P's contract; verify
exact fields against developer.2c2p.com. Endpoint paths are confirmed from
the 2C2P developer reference index.
version: '4.3'
contact:
name: 2C2P Developer
url: https://developer.2c2p.com
x-transport-notes: >-
All traffic is HTTPS request/response. Asynchronous results are delivered as
a backend notification webhook (2C2P POSTs a signed JWT to the merchant's
backendReturnUrl). There is no WebSocket or SSE transport.
servers:
- url: https://pgw.2c2p.com/payment/4.3
description: Production
- url: https://sandbox-pgw.2c2p.com/payment/4.3
description: Sandbox
tags:
- name: Payment Token
description: Initialize a payment and obtain a paymentToken.
- name: Do Payment
description: Execute a payment against a paymentToken.
- name: Payment Option
description: Retrieve available payment options and channel details.
- name: Inquiry
description: Query transaction result and status.
- name: Maintenance
description: Void / cancel, refund, and settle operations.
- name: Tokens
description: Card token and installment plan information.
- name: Exchange Rate
description: Currency exchange rates for DCC / cross-border.
paths:
/paymentToken:
post:
operationId: paymentToken
tags:
- Payment Token
summary: Create a payment token
description: >-
Initializes a payment and returns a paymentToken plus a webPaymentUrl
for the hosted payment page. On the wire the request/response are JWTs
(HS256, merchant secret key); the decoded payloads are modeled here.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentTokenRequest'
responses:
'200':
description: Decoded payment token response payload.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentTokenResponse'
/payment:
post:
operationId: doPayment
tags:
- Do Payment
summary: Do payment
description: >-
Executes a payment against a paymentToken, selecting the channel via the
payment code (card, e-wallet, QR, installment, pay-later, loyalty) and
supplying card / customer / browser / return-URL data.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DoPaymentRequest'
responses:
'200':
description: Decoded do-payment response payload.
content:
application/json:
schema:
$ref: '#/components/schemas/DoPaymentResponse'
/paymentOption:
post:
operationId: paymentOption
tags:
- Payment Option
summary: Get payment options
description: Returns the payment options / channels available for a paymentToken.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentOptionRequest'
responses:
'200':
description: Decoded payment option response payload.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
/paymentOptionDetails:
post:
operationId: paymentOptionDetails
tags:
- Payment Option
summary: Get payment option details
description: Returns detailed metadata for a specific payment option / channel.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentOptionRequest'
responses:
'200':
description: Decoded payment option details response payload.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
/paymentInquiry:
post:
operationId: paymentInquiry
tags:
- Inquiry
summary: Payment inquiry
description: >-
Retrieves the full result of a transaction by merchantID + invoiceNo,
returning amount, status, approval / reference codes, masked account /
card token, installment, and FX details.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentInquiryRequest'
responses:
'200':
description: Decoded payment inquiry response payload.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentInquiryResponse'
/transactionStatus:
post:
operationId: transactionStatus
tags:
- Inquiry
summary: Transaction status
description: Returns the current status of a transaction by paymentToken or invoiceNo.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentInquiryRequest'
responses:
'200':
description: Decoded transaction status response payload.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentInquiryResponse'
/cancelTransaction:
post:
operationId: cancelTransaction
tags:
- Maintenance
summary: Cancel / void a transaction
description: >-
Voids or cancels a transaction. Refund and settle operations are covered
by the 2C2P payment maintenance guides.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CancelTransactionRequest'
responses:
'200':
description: Decoded cancel/void response payload.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
/cardTokenInfo:
post:
operationId: cardTokenInfo
tags:
- Tokens
summary: Card token info
description: Retrieves information about a stored card token for recurring / returning-buyer use.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CardTokenInfoRequest'
responses:
'200':
description: Decoded card token info response payload.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
/cardInstallmentPlanInfo:
post:
operationId: cardInstallmentPlanInfo
tags:
- Tokens
summary: Card installment plan info
description: Returns the available installment plans for a card / merchant.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentInquiryRequest'
responses:
'200':
description: Decoded installment plan info response payload.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
/exchangeRate:
post:
operationId: exchangeRate
tags:
- Exchange Rate
summary: Exchange rate
description: >-
Retrieves currency exchange rates for a transaction, supporting dynamic
currency conversion (DCC). A JWT+JWS secured variant is also available.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExchangeRateRequest'
responses:
'200':
description: Decoded exchange rate response payload.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponse'
components:
schemas:
PaymentTokenRequest:
type: object
required:
- merchantID
- invoiceNo
- description
- amount
- currencyCode
properties:
merchantID:
type: string
description: Merchant identifier issued by 2C2P.
invoiceNo:
type: string
description: Unique merchant invoice / order number for this transaction.
description:
type: string
amount:
type: number
description: Transaction amount.
currencyCode:
type: string
description: ISO 4217 currency code (e.g. SGD, THB, USD).
paymentChannel:
type: array
items:
type: string
description: Optional list of allowed payment channels.
tokenize:
type: boolean
description: Request card tokenization for future / recurring use.
cardTokens:
type: array
items:
type: string
recurring:
type: boolean
invoicePrefix:
type: string
frontendReturnUrl:
type: string
format: uri
description: Browser redirect URL after payment.
backendReturnUrl:
type: string
format: uri
description: Server-to-server notification (webhook) URL.
locale:
type: string
PaymentTokenResponse:
type: object
properties:
webPaymentUrl:
type: string
format: uri
description: Hosted payment page URL to redirect the customer to.
paymentToken:
type: string
respCode:
type: string
description: Response code, e.g. "0000" for success.
respDesc:
type: string
DoPaymentRequest:
type: object
required:
- paymentToken
properties:
paymentToken:
type: string
payment:
type: object
description: The selected payment channel and its data.
properties:
code:
type: object
description: Channel / agent routing codes (channelCode, agentCode, etc.).
additionalProperties: true
data:
type: object
description: >-
Channel-specific data - for cards, an encryptedCardInfo /
securePayToken from Secure Fields plus cardholder details; for
other methods, the corresponding fields.
additionalProperties: true
clientIP:
type: string
clientID:
type: string
locale:
type: string
responseReturnUrl:
type: string
format: uri
browserDetails:
type: object
additionalProperties: true
DoPaymentResponse:
type: object
properties:
respCode:
type: string
respDesc:
type: string
data:
type: string
description: Redirect / 3DS / channel action data where applicable.
channelCode:
type: string
invoiceNo:
type: string
PaymentOptionRequest:
type: object
required:
- paymentToken
properties:
paymentToken:
type: string
locale:
type: string
PaymentInquiryRequest:
type: object
required:
- merchantID
properties:
merchantID:
type: string
invoiceNo:
type: string
paymentToken:
type: string
locale:
type: string
PaymentInquiryResponse:
type: object
properties:
merchantID:
type: string
invoiceNo:
type: string
amount:
type: number
currencyCode:
type: string
transactionDateTime:
type: string
agentCode:
type: string
channelCode:
type: string
approvalCode:
type: string
referenceNo:
type: string
accountNo:
type: string
description: Masked account / card number.
cardToken:
type: string
installmentPeriod:
type: integer
interestRate:
type: number
fxAmount:
type: number
fxRate:
type: number
fxCurrencyCode:
type: string
transactionStatus:
type: string
respCode:
type: string
respDesc:
type: string
CancelTransactionRequest:
type: object
required:
- merchantID
- invoiceNo
properties:
merchantID:
type: string
invoiceNo:
type: string
CardTokenInfoRequest:
type: object
required:
- merchantID
- cardToken
properties:
merchantID:
type: string
cardToken:
type: string
locale:
type: string
ExchangeRateRequest:
type: object
required:
- merchantID
- invoiceNo
properties:
merchantID:
type: string
invoiceNo:
type: string
amount:
type: number
currencyCode:
type: string
GenericResponse:
type: object
properties:
respCode:
type: string
respDesc:
type: string
additionalProperties: true