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