Coins.ph Payment / Partner Integration
Payment / Partner Integration API (Payment v2.7) — part of the Coins.ph developer platform.
OpenAPI Specification
{
"openapi": "3.0.3",
"info": {
"title": "Payment",
"description": "Coins.ph Partner Integration API v2.7\n\n## Authentication\nAll requests must include the following headers:\n- `X-COINS-APIKEY`: Your API key\n- `Timestamp`: Unix timestamp of the request\n- `Signature`: HMAC-SHA256 signature of the request\n\nRequests and webhook payloads must be signed using HMAC-SHA256 with the API secret.\n\n## Environments\n- **Sandbox**: `https://api.9001.pl-qa.coinsxyz.me`\n- **Production**: `https://api.pro.coins.ph`\n",
"version": "2.7",
"contact": {
"name": "Coins.ph Tech Ops",
"email": "tech_ops@coins.ph"
}
},
"servers": [
{
"url": "https://api.pro.coins.ph",
"description": "Production"
},
{
"url": "https://api.9001.pl-qa.coinsxyz.me",
"description": "Sandbox"
}
],
"security": [
{
"ApiKeyAuth": [],
"TimestampAuth": [],
"SignatureAuth": []
}
],
"tags": [
{
"name": "Collections - QRPH",
"description": "QRPH code generation and management"
},
{
"name": "Collections - Crypto",
"description": "Crypto deposit address"
},
{
"name": "Checkout",
"description": "Checkout creation and management"
},
{
"name": "Checkout Refund",
"description": "Checkout refund operations"
},
{
"name": "Tokenized Checkout",
"description": "Password-free (auto-debit) checkout"
},
{
"name": "Disbursements",
"description": "Cash-out and disbursement operations"
},
{
"name": "Refund",
"description": "Refund operations"
},
{
"name": "Reconciliation",
"description": "Reconciliation report"
},
{
"name": "Trading - Convert",
"description": "Convert trading operations"
},
{
"name": "Trading - OTC",
"description": "OTC trading for Business Account"
},
{
"name": "Order History",
"description": "Order history and details"
},
{
"name": "Utility",
"description": "Account balance, transfers, and utility endpoints"
},
{
"name": "Virtual Account",
"description": "Virtual account creation and management"
},
{
"name": "Scan to Pay",
"description": "QR code scan-to-pay payment operations"
}
],
"paths": {
"/openapi/fiat/v1/generate_qr_code": {
"post": {
"tags": [
"Collections - QRPH"
],
"summary": "Generate Dynamic QRPH",
"description": "Returns a dynamic QRPH code.",
"operationId": "generateDynamicQRPH",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"requestId",
"source",
"amount",
"currency"
],
"properties": {
"requestId": {
"type": "string",
"minLength": 15,
"maxLength": 19,
"description": "Unique string assigned by the partner for idempotency validation.",
"example": "3C1706X9619A7614YWS"
},
"type": {
"type": "string",
"enum": [
"DYNAMIC"
],
"description": "Can only be DYNAMIC. Going to be deprecated soon."
},
"source": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"description": "Assigned by the partner. Usually the abbreviation of the initiating party.",
"example": "CUSTOMIZABLE"
},
"amount": {
"type": "number",
"format": "decimal",
"description": "The amount represented by the QR code.",
"example": 200.99
},
"currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "Only the Philippine peso is supported.",
"example": "PHP"
},
"remark": {
"type": "string",
"maxLength": 99,
"description": "Assigned by the partner.",
"example": "CUSTOMIZABLE"
},
"expiredSeconds": {
"type": "integer",
"description": "Default QR code expiry is 900 seconds, maximum expiry can be up to 1800 seconds.",
"example": 1200
},
"qrCodeMerchantName": {
"type": "string",
"maxLength": 64,
"deprecated": true,
"description": "Usually used to replace the default name of the client.",
"example": "CUSTOMIZABLE"
},
"merchantId": {
"type": "string",
"maxLength": 64,
"description": "Server generated sub merchant id.",
"example": "6904028542363648"
},
"subMerchantId": {
"type": "string",
"maxLength": 64,
"description": "Sub-merchant ID.",
"example": "2904028542363648"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/FiatBaseResponse"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/DynamicQRPHResponse"
}
}
}
]
}
}
}
}
},
"parameters": [
{
"name": "recvWindow",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
},
"description": "Validity duration of the request in milliseconds after the timestamp."
}
]
}
},
"/openapi/fiat/v1/cancel_qr_code": {
"post": {
"tags": [
"Collections - QRPH"
],
"summary": "Cancel Dynamic QRPH",
"description": "Cancels a previously created dynamic QRPH code.",
"operationId": "cancelDynamicQRPH",
"parameters": [
{
"name": "referenceId",
"in": "query",
"required": true,
"schema": {
"type": "string",
"minLength": 15,
"maxLength": 19
},
"description": "Server generated reference id.",
"example": "1950928204919496214"
},
{
"name": "recvWindow",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
},
"description": "Validity duration of the request in milliseconds after the timestamp."
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/FiatBaseResponse"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/CancelQRPHResponse"
}
}
}
]
}
}
}
}
}
}
},
"/openapi/fiat/v1/generate/static/qr_code": {
"post": {
"tags": [
"Collections - QRPH"
],
"summary": "Generate Static QRPH",
"description": "Returns a static QRPH code.",
"operationId": "generateStaticQRPH",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"requestId",
"source",
"currency"
],
"properties": {
"requestId": {
"type": "string",
"minLength": 15,
"maxLength": 19,
"description": "Assigned by the partner for idempotency validation.",
"example": "3C1706X9619A7614YWS"
},
"source": {
"type": "string",
"minLength": 1,
"maxLength": 30,
"description": "Assigned by the partner.",
"example": "CUSTOMIZABLE"
},
"currency": {
"type": "string",
"minLength": 3,
"maxLength": 3,
"description": "Only the Philippine peso is supported.",
"example": "PHP"
},
"remark": {
"type": "string",
"maxLength": 99,
"description": "Assigned by the partner."
},
"qrCodeMerchantName": {
"type": "string",
"maxLength": 64,
"deprecated": true,
"description": "Usually used to replace the default name of the client."
},
"merchantId": {
"type": "string",
"maxLength": 64,
"description": "Server generated sub merchant id."
},
"subMerchantId": {
"type": "string",
"maxLength": 64,
"description": "Sub-merchant ID.",
"example": "2904028542363648"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/FiatBaseResponse"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/StaticQRPHResponse"
}
}
}
]
}
}
}
}
},
"parameters": [
{
"name": "recvWindow",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
},
"description": "Validity duration of the request in milliseconds after the timestamp."
}
]
}
},
"/openapi/fiat/v1/update/qr_code": {
"post": {
"tags": [
"Collections - QRPH"
],
"summary": "Update Static QRPH",
"description": "Change the state of a previously created static QRPH code.",
"operationId": "updateStaticQRPH",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"requestId",
"status"
],
"properties": {
"requestId": {
"type": "string",
"minLength": 15,
"maxLength": 19,
"description": "Assigned by the partner for idempotency validation."
},
"status": {
"type": "string",
"enum": [
"ACTIVE",
"SUSPEND"
],
"description": "State of the QR code."
}
}
}
}
}
},
"parameters": [
{
"name": "recvWindow",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
},
"description": "Validity duration of the request in milliseconds after the timestamp."
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/FiatBaseResponse"
},
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"requestId": {
"type": "string",
"example": "3C1706X9619A7614YWS"
},
"referenceId": {
"type": "string",
"example": "1950928204919496214"
},
"type": {
"type": "string",
"enum": [
"STATIC"
]
},
"qrCodeMerchantName": {
"type": "string",
"example": "CUSTOMIZABLE"
},
"status": {
"type": "string",
"enum": [
"ACTIVE",
"SUSPEND"
]
}
}
}
}
}
]
}
}
}
}
}
}
},
"/openapi/fiat/v1/get_qr_code/static/list": {
"get": {
"tags": [
"Collections - QRPH"
],
"summary": "Get Static QRPH List",
"description": "Returns a list of static QR codes previously created.",
"operationId": "getStaticQRPHList",
"parameters": [
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"ACTIVE",
"SUSPEND"
]
},
"description": "Filter by state of the QR code."
},
{
"name": "recvWindow",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
},
"description": "Validity duration of the request in milliseconds after the timestamp."
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/FiatBaseResponse"
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"requestId": {
"type": "string",
"example": "3C1706X9619A7614YWS"
},
"qrCode": {
"type": "string",
"description": "QR code string."
},
"status": {
"type": "string",
"enum": [
"ACTIVE",
"SUSPEND"
]
},
"qrCodeMerchantName": {
"type": "string",
"example": "CUSTOMIZABLE"
}
}
}
}
}
}
]
}
}
}
}
}
}
},
"/openapi/fiat/v1/get_qr_code": {
"get": {
"tags": [
"Collections - QRPH"
],
"summary": "Get QRPH Status",
"description": "Returns the current status of a previously created QRPH code.",
"operationId": "getQRPHStatus",
"parameters": [
{
"name": "requestId",
"in": "query",
"required": true,
"schema": {
"type": "string",
"minLength": 15,
"maxLength": 19
},
"description": "Assigned by the partner for idempotency validation."
},
{
"name": "recvWindow",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
},
"description": "Validity duration of the request in milliseconds after the timestamp."
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/FiatBaseResponse"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/QRPHStatusResponse"
}
}
}
]
}
}
}
}
}
}
},
"/openapi/wallet/v1/deposit/address": {
"get": {
"tags": [
"Collections - Crypto"
],
"summary": "Crypto Get Deposit Address",
"description": "Returns a crypto deposit address.",
"operationId": "getCryptoDepositAddress",
"parameters": [
{
"name": "coin",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Abbreviated token name.",
"example": "USDT"
},
{
"name": "network",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Abbreviated network name.",
"example": "XRP"
},
{
"name": "recvWindow",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
},
"description": "Validity duration of the request in milliseconds after the timestamp."
},
{
"name": "timestamp",
"in": "query",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
},
"description": "Unix timestamp indicating when the request was made.",
"example": 1747306565330
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"coin": {
"type": "string",
"example": "USDT"
},
"address": {
"type": "string",
"example": "rKrDJLGiSrKsRRtEQVgnWJnKALp5NJeDkC"
},
"addressTag": {
"type": "string",
"example": "1119001253"
}
}
}
}
}
}
}
}
},
"/openapi/fiat/v1/checkout/create-checkout": {
"post": {
"tags": [
"Checkout"
],
"summary": "Create Checkout",
"description": "Create an instance of a checkout.",
"operationId": "createCheckout",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateCheckoutRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/FiatBaseResponse"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/CreateCheckoutResponse"
}
}
}
]
}
}
}
}
},
"parameters": [
{
"name": "recvWindow",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
},
"description": "Validity duration of the request in milliseconds after the timestamp."
}
]
}
},
"/openapi/fiat/v1/checkout/status-check": {
"get": {
"tags": [
"Checkout"
],
"summary": "Get Checkout Status",
"description": "Returns the current status of a previously created checkout.",
"operationId": "getCheckoutStatus",
"parameters": [
{
"name": "checkoutId",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Server generated checkout id. This takes first priority.",
"example": "1984059672474453473"
},
{
"name": "refundId",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Server generated checkout id. This takes first priority.",
"example": "1984059672474453473"
},
{
"name": "requestId",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Assigned by the partner. This takes second priority.",
"example": "3C1706X9619A7614YWS"
},
{
"name": "recvWindow",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
},
"description": "Validity duration of the request in milliseconds after the timestamp."
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/FiatBaseResponse"
},
{
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/CheckoutStatusResponse"
}
}
}
]
}
}
}
}
}
}
},
"/openapi/fiat/v1/checkout/refund": {
"post": {
"tags": [
"Checkout Refund"
],
"summary": "Checkout Refund",
"description": "This Endpoint allows Merchants to initiate a refund for a Checkout transaction.\n\n**Webhook:** ✅ Supported (requires Coins' configuration)",
"operationId": "checkoutRefund",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"requestId",
"checkoutId",
"amount",
"currency",
"reason",
"method"
],
"properties": {
"requestId": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"description": "Unique Merchant refund request identifier (idempotency key).",
"example": "REQ123456789"
},
"checkoutId": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"description": "Original Checkout order ID to refund.",
"example": "CHK20240101000001"
},
"amount": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"description": "Refund amount. Must be a valid decimal with up to 2 decimal places.",
"example": "100.00"
},
"currency": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"description": "Currency code.",
"example": "PHP"
},
"reason": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Reason for refund.",
"example": "Customer requested refund"
},
"method": {
"type": "string",
"enum": [
"1"
],
"description": "Refund method. \"1\" = original route.",
"example": "1"
}
}
},
"example": {
"requestId": "REQ123456789",
"checkoutId": "CHK20240101000001",
"amount": "100.00",
"currency": "PHP",
"reason": "Customer requested refund",
"method": "1"
}
}
}
},
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "0 = success, non-zero = error code.",
"example": 0
},
"data": {
"$ref": "#/components/schemas/CheckoutRefundData"
}
}
},
"example": {
"status": 0,
"data": {
"refundId": "RFD987654321",
"checkoutId": "CHK20240101000001",
"requestId": "REQ123456789",
"amount": "100.00",
"currency": "PHP",
"status": "PROCESSING",
"refundReferenceId": "RREF202401150001",
"paymentReferenceId": "PREF202401100001",
"completedAt": null,
"createdAt": "2024-01-15T10:30:00Z"
}
}
}
}
}
},
"parameters": [
{
"name": "recvWindow",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
},
"description": "Validity duration of the request in milliseconds after the timestamp."
}
]
}
},
"/openapi/fiat/v1/checkout/refund/status-check": {
"get": {
"tags": [
"Checkout Refund"
],
"summary": "Refund Status Check",
"description": "This Endpoint allows Merchants to query the status of a Checkout refund by either `refundId` or `requestId`. At least one of the two must be provided.",
"operationId": "checkoutRefundStatusCheck",
"parameters": [
{
"name": "refundId",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"description": "Coins-generated refund ID. At least one of `refundId` or `requestId` must be provided.",
"example": "RFD987654321"
},
{
"name": "requestId",
"in": "query",
"required": false,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"description": "Merchant refund request ID (idempotency key). At least one of `refundId` or `requestId` must be provided.",
"example": "REQ123456789"
},
{
"name": "recvWindow",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
},
"description": "Validity duration of the request in milliseconds after the timestamp."
}
],
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "0 = success, non-zero = error code.",
"example": 0
},
"data": {
"$ref": "#/components/schemas/CheckoutRefundData"
}
}
},
"example": {
# --- truncated at 32 KB (230 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/coinsph/refs/heads/main/openapi/coinsph-payment-openapi.json