Coins.ph Scan to Pay API

openapi: 3.0.0
info:
  title: TRADING Account Scan to Pay 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: Scan to Pay
  description: QR code scan-to-pay payment operations
paths:
  /openapi/v1/scan-to-pay/payment-preview:
    post:
      tags:
      - Scan to Pay
      summary: Payment QRCode Decode
      description: Decode a QR code string and return payment preview information.
      operationId: paymentQRCodeDecode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - clientUserId
              - codeMsg
              properties:
                clientUserId:
                  type: string
                  description: Client user id.
                codeMsg:
                  type: string
                  description: QR code string.
                  example: 00020101021228600011ph.ppmi.p2m0111DCPHPHM1XXX0319213710352267898651205030115204601653036085402605802PH5909sand+90016007Boliney62380011ph.ppmi.p2m0519197338345306306048063047EAA
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/FiatBaseResponse'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/PaymentPreviewResponse'
              examples:
                success:
                  summary: Success
                  value:
                    status: 0
                    error: OK
                    data:
                      qrType: com.p2pqrpay
                      channel: PAYMENT_INTERNAL_P2P
                      channelSubject: DYNAMIC_QRPH
                      minLimit: '1'
                      maxLimit: '50000'
                      channelQRCodeMap:
                        clientUserId: '2136450830863779072'
                        amount: '60'
                        recipientAccountNumber: 1*****************6
                        fee: '0'
                        clientReqId: QRPH_P2M2139420973710274822
                        recipientName: xuqi-9001  z.
                        subQrType: DYNAMIC
                        recipientAddress: sa•••@coins.ph
                        productType: SCAN_TO_PAY
                        token: ee0b06d9b66e4931810907fe0ac7aa31
                    params: null
      parameters:
      - name: recvWindow
        in: query
        required: false
        schema:
          type: integer
          format: int64
        description: Validity duration of the request in milliseconds after the timestamp.
  /openapi/v1/scan-to-pay/payment-execution:
    post:
      tags:
      - Scan to Pay
      summary: Execute Payment
      description: Execute a scan-to-pay payment using the information returned from the payment-preview API.
      operationId: executeScanToPayPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - internalOrderId
              - currency
              - amount
              - channelName
              - channelSubject
              - extendInfo
              properties:
                internalOrderId:
                  type: string
                  description: KYB internal order id.
                currency:
                  type: string
                  description: Payment currency.
                  example: PHP
                amount:
                  type: string
                  description: Payment amount.
                  example: '50'
                channelName:
                  type: string
                  description: Payment channel returned from the /payment-preview API.
                  example: PAYMENT_INTERNAL_P2P
                channelSubject:
                  type: string
                  description: Payment channel subject returned from the /payment-preview API.
                  example: DYNAMIC_QRPH
                extendInfo:
                  $ref: '#/components/schemas/ChannelQRCodeMap'
                  description: QR channel Info returned from the /payment-preview API. Must include all fields in the channelQRCodeMap.
            example:
              internalOrderId: '20260130200000'
              currency: PHP
              amount: '50'
              channelName: PAYMENT_INTERNAL_P2P
              channelSubject: DYNAMIC_QRPH
              extendInfo:
                clientUserId: '2136450830863779072'
                amount: '60'
                recipientAccountNumber: 1*****************6
                fee: '0'
                clientReqId: QRPH_P2M2139420973710274822
                recipientName: xuqi-9001  z.
                subQrType: DYNAMIC
                recipientAddress: sa•••@coins.ph
                productType: SCAN_TO_PAY
                token: ee0b06d9b66e4931810907fe0ac7aa31
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/FiatBaseResponse'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/PaymentExecutionResponse'
              examples:
                success:
                  summary: Success
                  value:
                    status: 0
                    error: OK
                    data:
                      externalOrderId: '2139421355786203399'
                      internalOrderId: '20260130200000'
                      status: SUCCEEDED
                    params: null
      parameters:
      - name: recvWindow
        in: query
        required: false
        schema:
          type: integer
          format: int64
        description: Validity duration of the request in milliseconds after the timestamp.
  /openapi/v1/scan-to-pay/get-payment-result:
    get:
      tags:
      - Scan to Pay
      summary: Get Payment Result
      description: Retrieve the result of a scan-to-pay payment by internal order id.
      operationId: getScanToPayPaymentResult
      parameters:
      - name: internalOrderId
        in: query
        required: true
        schema:
          type: string
        description: ID of the order for which the user wishes to retrieve details.
        example: '20260130200000'
      - 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/PaymentResultResponse'
              examples:
                success:
                  summary: Success
                  value:
                    status: 0
                    error: OK
                    data:
                      externalOrderId: '2139421355786203399'
                      internalOrderId: '20260130200000'
                      paymentOrderId: ''
                      fiatCurrency: PHP
                      fiatAmount: '51.11'
                      transactionType: -1
                      transactionChannel: PAYMENT_INTERNAL_P2P
                      transactionSubject: DYNAMIC_QRPH
                      transactionChannelName: payment_internal_p2p
                      transactionSubjectName: ''
                      transactionSubjectType: ''
                      feeCurrency: PHP
                      channelFee: '0'
                      platformFee: '1.11'
                      status: SUCCEEDED
                      errorCode: ''
                      errorMessage: ''
                      completedTime: '2026-01-30T12:08:20.000+00:00'
                      source: OPEN_API
                      createdAt: '2026-01-30T12:08:20.000+00:00'
                      orderExtendedMap:
                        clientUserId: '2136450830863779072'
                        amount: '60'
                        fromUserId: '1442669428718174721'
                        linkOrderFee: '0.09'
                        fee: '0'
                        clientReqId: QRPH_P2M2139420973710274822
                        subQrType: DYNAMIC
                        linkOrderId: '2139421359040983304'
                        toUserId: '1864422461483746816'
                        orgId: '9001'
                        token: ee0b06d9b66e4931810907fe0ac7aa31
                        userIpCountry: Japan
                        recipientAccountNumber: '1864422461483746816'
                        x-user-ip: 35.75.185.122
                        dualWriteMode: DUAL_WRITE_LEGACY_PRIMARY
                        recipientName: xuqi-9001  z.
                        userIp: 35.75.185.122
                        taxFee: '0'
                        recipientAddress: sa•••@coins.ph
                        productType: SCAN_TO_PAY
                      dealCancel: false
                    params: null
  /openapi/v1/account/create-account:
    post:
      tags:
      - Scan to Pay
      summary: Create Account
      description: 'Create a KYC account for scan-to-pay user.


        **Note:** Parameters need to be passed using Query String; form-data and json methods cannot be used. The contentType must be multipart/form-data.'
      operationId: createKycAccount
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - requestId
              - customerId
              - callbackDefaultUrl
              - customerIp
              - customerSource
              - customerUserAgent
              - firstName
              - lastName
              - gender
              - dateOfBirth
              - country
              - nationality
              - state
              - city
              - street
              - postalCode
              - employmentStatus
              - purposeOfAccount
              - idType
              - idNumber
              - expireDate
              - frontIdImage
              - facePhoto
              - frontIdImageMd5
              - facePhotoMd5
              properties:
                requestId:
                  type: string
                  description: Unique order ID generated by the merchant.
                customerId:
                  type: string
                  description: Customer ID on the merchant side.
                email:
                  type: string
                  description: Customer's email, at least one of the email or phone numbers must be provided.
                phone:
                  type: string
                  description: 'The customer''s mobile phone number must be formatted as [country code] [local number], for example: +63 9271234567.'
                notifyUrl:
                  type: string
                  description: User creation result notification URL.
                callbackDefaultUrl:
                  type: string
                  description: Default URL to redirect users based on registration results.
                callbackSuccessUrl:
                  type: string
                  description: URL for redirecting users after successful registration.
                callbackFailureUrl:
                  type: string
                  description: URL for redirecting upon registration failure.
                callbackCancelUrl:
                  type: string
                  description: URL for user cancellation of registration redirection.
                customerIp:
                  type: string
                  description: Customer's own IP address.
                customerSource:
                  type: string
                  enum:
                  - WEB
                  - IOS
                  - ANDROID
                  description: The source of the customer's device.
                customerUserAgent:
                  type: string
                  description: Customer's user-agent.
                firstName:
                  type: string
                  description: First name.
                middleName:
                  type: string
                  description: Middle name.
                lastName:
                  type: string
                  description: Last name.
                gender:
                  type: integer
                  enum:
                  - 0
                  - 1
                  - 2
                  description: 'Gender: 0 - Other, 1 - Male, 2 - Female.'
                dateOfBirth:
                  type: string
                  description: 'The format is: yyyy-MM-dd.'
                  example: '1990-01-01'
                country:
                  type: string
                  description: Current country of residence. Refer to CountryEnum, use the code field value.
                nationality:
                  type: string
                  description: Nationality. Refer to CountryEnum, use the code field value.
                state:
                  type: string
                  description: Current state (province) of residence.
                city:
                  type: string
                  description: Current city of residence.
                street:
                  type: string
                  description: Current residential address.
                postalCode:
                  type: string
                  description: Current residence postal code.
                employmentStatus:
                  type: string
                  enum:
                  - employed
                  - self_e
                  - freelance
                  - unemployed
                  - retired
                  - student
                  description: Employment status. Refer to EmploymentStatusEnum.
                industry:
                  type: string
                  description: Industry. If employmentStatus is employed, this field is required.
                companyName:
                  type: string
                  description: Company Name. If employmentStatus is employed, this field is required.
                jobTitle:
                  type: string
                  description: Position. If employmentStatus is employed, this field is required.
                purposeOfAccount:
                  type: string
                  enum:
                  - legal
                  - crypto
                  - both
                  description: Account purposes.
                idType:
                  type: string
                  description: 'Type of ID, e.g.: passport. Refer to IdTypeEnum.'
                idNumber:
                  type: string
                  description: ID number.
                expireDate:
                  type: string
                  description: 'ID expiration date, the format is: yyyy-MM-dd.'
                  example: '2030-12-31'
                frontIdImage:
                  type: string
                  format: binary
                  description: 'Image of the front of the id. Supported formats: jpg, png, jpeg. Max size: 2M.'
                backIdImage:
                  type: string
                  format: binary
                  description: 'Backside photo of the evidence. Supported formats: jpg, png, jpeg. Max size: 2M.'
                facePhoto:
                  type: string
                  format: binary
                  description: 'Selfie photo. Supported formats: jpg, png, jpeg. Max size: 2M.'
                frontIdImageMd5:
                  type: string
                  description: MD5 value of the frontIdImage file.
                backIdImageMd5:
                  type: string
                  description: MD5 value of the backIdImage file.
                facePhotoMd5:
                  type: string
                  description: MD5 value of the facePhoto file.
                businessScenarios:
                  type: string
                  description: Scan to Pay need input scan_to_pay.
                  example: scan_to_pay
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAccountResponse'
              examples:
                success:
                  summary: Success
                  value:
                    status: PENDING
                    requestId: '2021697969472158281'
                    customerId: xxxxxx
                    coinsUserId: 0
                    redirectUrl: https://pro.coins.ph/payment/auth?requestId=2021697969472158281
      parameters:
      - name: recvWindow
        in: query
        required: false
        schema:
          type: integer
          format: int64
        description: Validity duration of the request in milliseconds after the timestamp.
  /openapi/v1/account/get-create-account-request:
    get:
      tags:
      - Scan to Pay
      summary: Get Created User Request
      description: Retrieve the status and details of a KYC account creation request.
      operationId: getCreateAccountRequest
      parameters:
      - name: requestId
        in: query
        required: true
        schema:
          type: string
        description: requestId parameter when creating a user.
      - name: customerId
        in: query
        required: true
        schema:
          type: string
        description: customerId parameter when creating a user.
      - 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:
                $ref: '#/components/schemas/GetCreateAccountResponse'
              examples:
                success:
                  summary: Success
                  value:
                    requestId: '2021697969472158281'
                    customerId: xxxx
                    status: APPROVED
                    coinsUserId: 2021697969472158200
                    phone: +63 9271234567
                    email: example@gmail.com
                    firstName: ''
                    lastName: ''
                    middleName: ''
components:
  schemas:
    FiatBaseResponse:
      type: object
      properties:
        status:
          type: integer
          description: 0 = success, non-zero = error code
          example: 0
        error:
          type: string
          example: OK
        params:
          type: object
          nullable: true
    ChannelQRCodeMap:
      type: object
      required:
      - clientUserId
      - amount
      - subQrType
      - productType
      - clientReqId
      - token
      properties:
        clientUserId:
          type: string
          description: Debit user id.
        amount:
          type: string
          description: Amount.
        recipientAccountNumber:
          type: string
          description: Recipient account number.
        recipientName:
          type: string
          description: Recipient name.
        recipientAddress:
          type: string
          description: Recipient address.
        subQrType:
          type: string
          description: QR type.
        productType:
          type: string
          description: 'Business product type: SCAN_TO_PAY.'
          example: SCAN_TO_PAY
        clientReqId:
          type: string
          description: Request id.
        token:
          type: string
          description: Encrypted token.
        tfrName:
          type: string
          description: Recipient name.
        tfrBnkCode:
          type: string
          description: Recipient bank code.
        tfrAcctNo:
          type: string
          description: Recipient account number.
        fee:
          type: string
          description: Fee amount.
    PaymentPreviewResponse:
      type: object
      required:
      - qrType
      - channel
      - channelSubject
      - channelQRCodeMap
      properties:
        qrType:
          type: string
          description: QR code type.
          example: ph.ppmi.p2m
        channel:
          type: string
          description: Payment channel.
        channelSubject:
          type: string
          description: Payment channel subject.
        minLimit:
          type: string
          description: Minimum transaction amount.
        maxLimit:
          type: string
          description: Maximum transaction amount.
        channelQRCodeMap:
          $ref: '#/components/schemas/ChannelQRCodeMap'
          description: QR channel Info.
    CreateAccountResponse:
      type: object
      required:
      - status
      - requestId
      - customerId
      - redirectUrl
      properties:
        status:
          type: string
          enum:
          - APPROVED
          - FAILED
          - REJECTED
          - PENDING
          - CANCELLED
          description: 'Status, reference enumeration: StatusEnum.'
        requestId:
          type: string
          description: The requestId passed in when the customer requests.
        customerId:
          type: string
          description: customerId passed in when the customer requests.
        coinsUserId:
          type: integer
          format: int64
          description: The external user ID of the user in Coins, which is only available after successful registration.
        redirectUrl:
          type: string
          description: Jump verification page.
    PaymentResultResponse:
      type: object
      required:
      - externalOrderId
      - internalOrderId
      - paymentOrderId
      - fiatCurrency
      - fiatAmount
      - transactionType
      - transactionChannel
      - transactionSubject
      - transactionSubjectType
      - transactionChannelName
      - transactionSubjectName
      - feeCurrency
      - channelFee
      - platformFee
      - status
      - errorCode
      - errorMessage
      - completedTime
      - source
      - createdAt
      - orderExtendedMap
      - dealCancel
      properties:
        externalOrderId:
          type: string
          description: Coins internal ID.
        internalOrderId:
          type: string
          description: The unique order id generated by the server.
        paymentOrderId:
          type: string
          description: The payment order id generated by the channel.
        fiatCurrency:
          type: string
          description: PHP as it is the only currency currently supported.
        fiatAmount:
          type: string
          description: The order amount.
        transactionType:
          type: string
          description: 1 means cash in, -1 means cash out.
        transactionChannel:
          type: string
          description: The first-level channel to order it belongs.
        transactionSubject:
          type: string
          description: The channel code of order.
        transactionSubjectType:
          type: string
          description: Channel type.
        transactionChannelName:
          type: string
          description: First level channel Name.
        transactionSubjectName:
          type: string
          description: Channel Name.
        feeCurrency:
          type: string
          description: PHP as it is the only currency currently supported.
        channelFee:
          type: string
          description: The fee of order always 0. Deprecated, see platformFee.
        platformFee:
          type: string
          description: The fee of order.
        status:
          type: string
          enum:
          - PENDING
          - SUCCEEDED
          - FAILED
          - CANCEL
          description: 'Indicates the current state of the order.

            - PENDING: The order is still being processed and is not in a final state.

            - SUCCEEDED: The order has been successfully processed.

            - FAILED: The order processing has failed.

            - CANCEL: The order has been canceled by the user and is considered equivalent to a failure.


            Only orders in a final state (SUCCEEDED, FAILED, or CANCEL) are considered complete and reliable for further actions. Avoid relying on orders in a non-final state (PENDING) as their status may change.'
        errorCode:
          type: string
          description: Order fail with errorCode.
        errorMessage:
          type: string
          description: Order fail with error message.
        completedTime:
          type: string
          description: The time of order completed.
        source:
          type: string
          description: Order create client Type, such as WEB, ANDROID, IOS, open-api.
        createdAt:
          type: string
          description: The time of order created.
        orderExtendedMap:
          type: object
          description: The order extend data.
          additionalProperties:
            type: string
        dealCancel:
          type: boolean
          description: If order can be canceled, value will be true.
    GetCreateAccountResponse:
      type: object
      required:
      - requestId
      - customerId
      - status
      - firstName
      - middleName
      properties:
        requestId:
          type: string
          description: The requestId passed in when the customer requests.
        customerId:
          type: string
          description: customerId passed in when the customer requests.
        status:
          type: string
          enum:
          - APPROVED
          - FAILED
          - REJECTED
          - PENDING
          - CANCELLED
          description: 'Status, reference enumeration: StatusEnum.'
        coinsUserId:
          type: integer
          format: int64
          description: The external user ID of the user in Coins, which is only available after successful registration.
        phone:
          type: string
          description: Phone number.
        email:
          type: string
          description: Email.
        firstName:
          type: string
          description: First name.
        lastName:
          type: string
          description: Last name.
        middleName:
          type: string
          description: Middle name.
    PaymentExecutionResponse:
      type: object
      required:
      - externalOrderId
      - internalOrderId
      - status
      properties:
        externalOrderId:
          type: string
          description: Coin's internal ID.
        internalOrderId:
          type: string
          description: The unique order id generated by the server or the passed internalOrderId.
        status:
          type: string
          enum:
          - PENDING
          - SUCCEEDED
          - FAILED
          - CANCEL
          description: 'Indicates the current state of the order.

            - PENDING: The order is still being processed and is not in a final state.

            - SUCCEEDED: The order has been successfully processed.

            - FAILED: The order processing has failed.

            - CANCEL: The order has been canceled by the user and is considered equivalent to a failure.


            Only orders in a final state (SUCCEEDED, FAILED, or CANCEL) are considered complete and reliable for further actions. Avoid relying on orders in a non-final state (PENDING) as their status may change.'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-COINS-APIKEY
x-readme:
  proxy-enabled: false