Coins.ph Account Validation API
The Account Validation API from Coins.ph — 2 operation(s) for account validation.
OpenAPI Specification
openapi: 3.0.0
info:
title: TRADING Account Account Validation API
version: 1.0.0
description: API reference for Account management — Coins.ph
servers:
- url: https://api.pro.coins.ph
description: Production
- url: https://api.9001.pl-qa.coinsxyz.me
description: Sandbox
tags:
- name: Account Validation
paths:
/openapi/fiat/v1/account-validation/create:
post:
summary: Submit Account Validation Request
description: 'Create an account validation request. Returns `PENDING` immediately.
Use the `validationRequestId` from the response to poll the status-check endpoint.
**Idempotency**: Submitting the same `requestId` twice returns the original result without creating a duplicate validation.
'
operationId: createAccountValidation
tags:
- Account Validation
parameters:
- name: signature
in: header
required: true
schema:
type: string
description: HMAC-SHA256 signature of the raw JSON request body
- name: timestamp
in: header
required: true
schema:
type: string
description: Current Unix timestamp in milliseconds
- name: recvWindow
in: header
required: true
schema:
type: integer
maximum: 60000
description: Time window in milliseconds for request validity (max 60000)
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateValidationRequest'
examples:
internal_phone:
summary: INTERNAL — look up by phone
value:
requestId: VAL-20240423-001
verificationMethod: INTERNAL
transactionChannel: COINS
transactionSubject: coins.ph
currency: PHP
accountInfo:
phone: 09171234567
accountName: Juan Dela Cruz
penny_drop:
summary: PENNY_DROP — real-time bank verification
value:
requestId: VAL-20240423-002
verificationMethod: PENNY_DROP
transactionChannel: INSTAPAY
transactionSubject: BDO
currency: PHP
accountInfo:
accountNumber: '1234567890'
accountName: Juan Dela Cruz
auto:
summary: AUTO — recommended (saves cost when cache hit)
value:
requestId: VAL-20240423-003
verificationMethod: AUTO
transactionChannel: INSTAPAY
transactionSubject: BPI
currency: PHP
accountInfo:
accountNumber: '9876543210'
accountName: Maria Santos
responses:
'200':
description: Validation request created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateValidationResponse'
example:
status: 0
error: null
data:
requestId: VAL-20240423-001
validationRequestId: AV20240423000001
status: PENDING
createdAt: 1713859200000
accountInfo:
accountNumber: '1234567890'
accountName: Juan Dela Cruz
'400':
description: Validation error on request body fields
'401':
description: Invalid signature or API key
'403':
description: Non-PH or non-fiat account. This API is restricted to Philippine fiat accounts only.
'408':
description: Timestamp outside recvWindow. Sync system clock; ensure recvWindow ≤ 60000 ms.
'429':
description: Rate limit exceeded
'500':
description: Internal server error
/openapi/fiat/v1/account-validation/status-check:
get:
summary: Query Account Validation Status
description: 'Query the result of an account validation request.
At least one of `requestId` or `validationRequestId` must be provided.
`validationRequestId` takes precedence if both are provided.
**Polling recommendation**: Send the first poll 3 seconds after submission, then use exponential backoff with a max interval of 30 seconds.
'
operationId: getAccountValidationStatus
tags:
- Account Validation
parameters:
- name: X-COINS-APIKEY
in: header
required: true
schema:
type: string
description: Your API key
- name: signature
in: header
required: true
schema:
type: string
description: HMAC-SHA256 signature of the query string
- name: timestamp
in: header
required: true
schema:
type: string
description: Current Unix timestamp in milliseconds
- name: requestId
in: query
required: false
schema:
type: string
description: Merchant idempotency key (one of requestId or validationRequestId required)
- name: validationRequestId
in: query
required: false
schema:
type: string
description: Coins-generated validation request ID. Takes precedence over requestId if both are provided.
example: AV20240423000001
responses:
'200':
description: Validation status retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationStatusResponse'
examples:
success_database:
summary: SUCCESS — DATABASE method
value:
status: 0
error: null
data:
requestId: VAL-20240423-001
validationRequestId: AV20240423000001
status: SUCCESS
accountStatus: VALID
verificationMethod: DATABASE
nameMatchStatus: MATCH
nameMatchScore: 95
activityPeriod: 1_MONTH
createdAt: 1713859200000
updatedAt: 1713859205000
success_auto_penny_drop:
summary: SUCCESS — AUTO upgraded to PENNY_DROP
value:
status: 0
error: null
data:
requestId: VAL-20240423-003
validationRequestId: AV20240423000003
status: SUCCESS
accountStatus: VALID
verificationMethod: AUTO
actualMethod: PENNY_DROP
nameMatchStatus: PARTIAL_MATCH
nameMatchScore: 72
fee:
currency: PHP
amount: '1.00'
createdAt: 1713859200000
updatedAt: 1713859260000
success_internal:
summary: SUCCESS — INTERNAL method
value:
status: 0
error: null
data:
requestId: VAL-20240423-002
validationRequestId: AV20240423000002
status: SUCCESS
accountStatus: VALID
verificationMethod: INTERNAL
nameMatchStatus: MATCH
nameMatchScore: 100
remainingDepositLimit:
daily:
currency: PHP
amount: '50000.00'
monthly:
currency: PHP
amount: '200000.00'
annual:
currency: PHP
amount: '500000.00'
createdAt: 1713859200000
updatedAt: 1713859202000
pending:
summary: Still processing
value:
status: 0
error: null
data:
requestId: VAL-20240423-001
validationRequestId: AV20240423000001
status: PENDING
verificationMethod: PENNY_DROP
createdAt: 1713859200000
updatedAt: 1713859200000
failed:
summary: FAILED — invalid account
value:
status: 0
error: null
data:
requestId: VAL-20240423-004
validationRequestId: AV20240423000004
status: FAILED
accountStatus: INVALID
verificationMethod: PENNY_DROP
code: AC14
message: Account closed
createdAt: 1713859200000
updatedAt: 1713859300000
'400':
description: Missing parameter — provide at least one of requestId or validationRequestId
'401':
description: Invalid signature or API key
'429':
description: Rate limit exceeded
'500':
description: Internal server error
components:
schemas:
FiatMoney:
type: object
properties:
currency:
type: string
description: ISO 4217 currency code
example: PHP
amount:
type: string
description: Decimal amount
example: '1.00'
CreateValidationResponse:
type: object
properties:
status:
type: integer
example: 0
error:
type: string
nullable: true
data:
type: object
properties:
requestId:
type: string
description: Merchant idempotency key (echoed back)
validationRequestId:
type: string
description: Coins-generated validation request ID. Use this to query the result.
example: AV20240423000001
status:
type: string
enum:
- PENDING
description: Always PENDING on creation
createdAt:
type: integer
format: int64
description: Request creation time (Unix milliseconds, UTC)
accountInfo:
$ref: '#/components/schemas/AccountInfo'
ValidationStatusResponse:
type: object
properties:
status:
type: integer
example: 0
error:
type: string
nullable: true
data:
type: object
properties:
requestId:
type: string
description: Merchant idempotency key
validationRequestId:
type: string
description: Coins-generated validation request ID
status:
type: string
enum:
- PENDING
- SUCCESS
- FAILED
description: 'Processing status:
- `PENDING`: Validation request received and queued for processing
- `SUCCESS`: Validation completed. Check accountStatus for the result.
- `FAILED`: Validation failed. Check code and message for the reason.
'
accountStatus:
type: string
enum:
- VALID
- INVALID
description: 'Validation conclusion (present when status=SUCCESS):
- `VALID`: Account exists, is active, and KYC level meets the requirement
- `INVALID`: Account does not exist, is inactive, or KYC level is insufficient
'
verificationMethod:
type: string
enum:
- INTERNAL
- DATABASE
- PENNY_DROP
- AUTO
description: Requested verification method
actualMethod:
type: string
enum:
- DATABASE
- PENNY_DROP
description: Actual method used (only present for AUTO method)
accountInfo:
$ref: '#/components/schemas/AccountInfo'
nameMatchStatus:
type: string
enum:
- MATCH
- PARTIAL_MATCH
- MISMATCH
- N/A
description: 'Name match result (present when status=SUCCESS):
- `MATCH`: Submitted name exactly matches the account holder name
- `PARTIAL_MATCH`: Name closely matches (minor differences). Proceed with caution.
- `MISMATCH`: Name does not match the account holder name. Do not transfer funds.
- `N/A`: Name matching was not performed (accountName was not provided)
'
nameMatchScore:
type: integer
minimum: 0
maximum: 100
description: Name similarity score, 0–100 (present when status=SUCCESS)
activityPeriod:
type: string
enum:
- 7_DAYS
- 1_MONTH
- 3_MONTHS
- 6_MONTHS
- 1_YEAR
- OVER_1_YEAR
description: Account activity period (DATABASE method only)
remainingDepositLimit:
$ref: '#/components/schemas/RemainingDepositLimit'
fee:
$ref: '#/components/schemas/FiatMoney'
description: Verification fee charged (PENNY_DROP method only)
pennyDropAmount:
$ref: '#/components/schemas/FiatMoney'
description: Actual micro-transfer amount sent to the bank account, 1 or 2 PHP (PENNY_DROP method only)
code:
type: string
description: Error code (present when status=FAILED)
example: AC14
message:
type: string
description: Error description (present when status=FAILED)
example: Account closed
createdAt:
type: integer
format: int64
description: Creation time (Unix milliseconds, UTC)
updatedAt:
type: integer
format: int64
description: Last updated time (Unix milliseconds, UTC)
CreateValidationRequest:
type: object
required:
- requestId
- verificationMethod
- transactionChannel
- transactionSubject
- currency
- accountInfo
properties:
requestId:
type: string
minLength: 1
maxLength: 64
description: Merchant idempotency key. Reusing the same requestId returns the original result without creating a new validation.
example: VAL-20240423-001
verificationMethod:
type: string
enum:
- INTERNAL
- DATABASE
- PENNY_DROP
- AUTO
description: 'Validation method:
- `INTERNAL`: Look up Coins user database by phone / email / account name. No fee.
- `DATABASE`: Look up historical transaction records (shared across merchants). No fee.
- `PENNY_DROP`: Send a real micro-transfer (1 or 2 PHP, random) to verify live bank account. Fee applies.
- `AUTO`: Try DATABASE first; auto-upgrade to PENNY_DROP if no record found. Fee per actual method.
'
transactionChannel:
type: string
enum:
- COINS
- INSTAPAY
- SWIFTPAY_PESONET
description: Channel. Use `COINS` for INTERNAL method; `INSTAPAY` or `SWIFTPAY_PESONET` for external methods.
transactionSubject:
type: string
description: Bank code (e.g. BDO, BPI) or `coins.ph` for Coins internal.
example: BDO
currency:
type: string
minLength: 3
maxLength: 3
description: Currency code.
example: PHP
accountInfo:
$ref: '#/components/schemas/AccountInfo'
AccountInfo:
type: object
properties:
accountNumber:
type: string
description: Bank account number. Required for DATABASE / PENNY_DROP / AUTO methods.
accountName:
type: string
description: Account holder name. Required for DATABASE / PENNY_DROP / AUTO; optional for INTERNAL. If omitted, nameMatchStatus returns N/A.
phone:
type: string
description: Phone number. For INTERNAL method only.
example: 09171234567
email:
type: string
description: Email address. For INTERNAL method only.
RemainingDepositLimit:
type: object
description: Remaining deposit limits (INTERNAL method only)
properties:
daily:
$ref: '#/components/schemas/FiatMoney'
monthly:
$ref: '#/components/schemas/FiatMoney'
annual:
$ref: '#/components/schemas/FiatMoney'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-COINS-APIKEY
x-readme:
proxy-enabled: false