---
title: "Get Payment by Reference ID"
method: GET
path: "/v1/payment/orders"
tags: ["Payment Services"]
---

# Get Payment by Reference ID

`GET /v1/payment/orders`

Payment details service.

## Query parameters

- `reference_id` string, required

## Headers

- `Content-Type` string, required
- `Accept` string, required

## Response `200`

Payment details response

- union
  - PixPaymentDetailResponse
    - `store` object
      - `code` string — Store identifier.
      - `category` string — Four-digit ISO 18245 merchant category code.
    - `transaction` object, required
      - `reference_id` string, required — Transaction identifier, generated by client. (Maximum of 50 characters - Unique per transaction).
      - `business_id` string — Business ID. The ID of the transaction related with this payment.
      - `account` string — Client account number provided by Koin.
      - `amount` object, required
        - `currency_code` string, required — Currency code (ISO 4217)
        - `value` number, required — Payment total amount
      - `provider_reference` object — Provider reference data
        - `tx_id` string, required — Provider order identifier, used to identify the order in the bank
        - `end_to_end_id` string — Provider payment identifier, used to identify the payment in the bank. (Mandatory data when the payment is Collected)
    - `order_id` string, required — Order ID returned by create payment service
    - `status` object, required
      - `type` 'Opened' | 'Published' | 'Cancelled' | 'Collected' | 'Refunded' | 'Failed', required — Payment status.
      - `date` string, date-time, required — Status change date (ISO 8601 date format)
      - `error` StatusError — Error details. Present when the payment failed and error information is available.
        - `code` string — Error code.
        - `message` string — Error message.
    - `locations` object[] — Locations data
      - `url` string — Url to download the QR code. (Not yet available from the central bank)
      - `qr_code` string, required — Information to show the QR code on your payment page, image in base64.
      - `emv` string, required — EMV string representing the QR code data
    - `payment_method` object, required
      - `code` 'PIX' | 'CARD', required — Payment method code.
      - `expiration_date` string, date-time — Expiration date. (In ISO 8601 format with UTC in GMT 0)
      - `payment_key` string — Represents the pix key (Maximum of 100 characters)
    - `payer` object
      - `document` object
        - `type` 'cpf' | 'cnpj', required — Payer document type (cpf, cnpj)
        - `number` string, required — Payer document number
        - `nationality` string — Payer nationality (two-letter ISO 3166 country code)
      - `first_name` string — Payer first name. If the length of the field exceeds 100 characters it will be truncated.
      - `last_name` string — Payer second name. If the length of the field exceeds 100 characters it will be truncated.
      - `full_name` string — Full name. If the length of the field exceeds 100 characters it will be truncated.
      - `email` string — Payer email.
      - `phone` object
        - `area` string, required — Phone area code
        - `number` string, required — Phone number
        - `type` string — Phone type (e.g., Mobile)
    - `provider` object
      - `code` string — Provider code for the integration used to process the transaction.
      - `payer` object
        - `document` object
          - `type` 'cpf' | 'cnpj', required — Payer document type (cpf, cnpj)
          - `number` string, required — Payer document number
        - `full_name` string — Full name. If the length of the field exceeds 100 characters it will be truncated.
        - `account` object
          - `ispb` string — Brazilian Payment System Identifier (eight-number length).
          - `agency` string — Agency of the account.
          - `code` string — Payer account number.
          - `type` string — Payer account type.
    - `refunds` RefundDetailResponse[] — Refunds data
      - `id` string, required — Unique refund identifier.
      - `amount` object, required
        - `currency_code` string, required — Currency code (ISO 4217)
        - `value` number, required — Refund total amount
      - `status` StatusRefund, required
        - `type` 'Refunded' | 'InProgress' | 'Failed', required — Payment status.
        - `date` string, date-time, required — Status change date (ISO 8601 date format)
        - `error` StatusError — Error details. Present when the payment failed and error information is available.
          - `code` string — Error code.
          - `message` string — Error message.
      - `code` string — Standardized error code (applies only for error cases)
      - `message` string — Message associated with the error code (applies only for error cases)
      - `causes` string[] — List of strings that details the cause that generates the error.
    - `code` string — Standardized error code (applies only for error cases)
    - `message` string — Message associated with the error code (applies only for error cases)
  - BNPLPaymentDetailResponse
    - `store` object
      - `code` string — Store identifier.
      - `category` string — Four-digit ISO 18245 merchant category code.
    - `transaction` object, required
      - `reference_id` string, required — Transaction identifier, generated by client. (Maximum of 50 characters - Unique per transaction).
      - `business_id` string — Business ID. The ID of the transaction related with this payment.
      - `account` string — Client account number provided by Koin.
      - `amount` object, required
        - `currency_code` string, required — Currency code (ISO 4217)
        - `value` number, required — Payment total amount
    - `order_id` string — Order ID returned by create payment service
    - `status` object, required
      - `type` string, required — Payment status.
      - `reason` string — Payment status reason
      - `date` string, date-time, required — Status change date (ISO 8601 date format)
      - `error` StatusError — Error details. Present when the payment failed and error information is available.
        - `code` string — Error code.
        - `message` string — Error message.
    - `payment_method` object, required
      - `code` 'PIX' | 'CARD', required — Payment method code.
      - `expiration_date` string, date-time — Expiration date. (In ISO 8601 format with UTC in GMT 0)
    - `payer` object
      - `document` object
        - `type` 'cpf', required — Payer document type cpf
        - `number` string, required — Payer document number
        - `nationality` string — Payer nationality (two-letter ISO 3166 country code)
      - `first_name` string — Payer first name. If the length of the field exceeds 100 characters it will be truncated.
      - `last_name` string — Payer second name. If the length of the field exceeds 100 characters it will be truncated.
      - `full_name` string — Full name. If the length of the field exceeds 100 characters it will be truncated.
      - `email` string — Payer email.
      - `phone` object
        - `area` string, required — Phone area code
        - `number` string, required — Phone number
        - `type` string — Phone type (e.g., Mobile)
      - `birthdate` string — Only payment method BNPL.
    - `installment_option` object — Selected installment option (Only for BNPL payment method)
      - `installments` integer — Number of installments
      - `installment_rate` string — Installment rate
      - `installment_amount` number — Installment amount
      - `total_amount` number — Payment total amount
      - `first_due_date` string, date-time — Installment first due date (ISO 8601 date format)
      - `iof` number — IOF rate
      - `cet` number — CET rate
      - `cet_am` number — Monthly CET rate
      - `option_id` string — Installment option identifier
      - `incoming_percent_value` number — Down payment percentage
      - `incoming_value` number — Down payment amount
      - `discount` object
        - `original_installment_value` number — Original amount before applying the discount
        - `value` number — Discount amount
        - `percent` number — Discount percentage
      - `ui` object
        - `layout` object
          - `tags` string[]
          - `highlighted` boolean
          - `sorted` number
        - `hints` object
          - `birthdate` object
            - `required` boolean
      - `locations` object[] — Locations data
        - `url` string — Url to download the QR code. (Not yet available from the central bank)
        - `qr_code` string, required — Information to show the QR code on your payment page, image in base64.
        - `emv` string, required — EMV string representing the QR code data
        - `expires` string
    - `return_url` string — The URL you need to redirect the end user back. Only payment method BNPL.
    - `refunds` RefundDetailResponse[] — Refunds data
      - `id` string, required — Unique refund identifier.
      - `amount` object, required
        - `currency_code` string, required — Currency code (ISO 4217)
        - `value` number, required — Refund total amount
      - `status` StatusRefund, required
        - `type` 'Refunded' | 'InProgress' | 'Failed', required — Payment status.
        - `date` string, date-time, required — Status change date (ISO 8601 date format)
        - `error` StatusError — Error details. Present when the payment failed and error information is available.
          - `code` string — Error code.
          - `message` string — Error message.
      - `code` string — Standardized error code (applies only for error cases)
      - `message` string — Message associated with the error code (applies only for error cases)
      - `causes` string[] — List of strings that details the cause that generates the error.
    - `code` string — Standardized error code (applies only for error cases)
    - `message` string — Message associated with the error code (applies only for error cases)
  - CardPaymentDetailResponse
    - `store` object
      - `code` string — Store identifier.
      - `category` string — Four-digit ISO 18245 merchant category code.
    - `transaction` object, required
      - `reference_id` string, required — Transaction identifier, generated by client. (Maximum of 50 characters - Unique per transaction).
      - `business_id` string — Business ID. The ID of the transaction related with this payment.
      - `account` string — Client account number provided by Koin.
      - `amount` object, required
        - `currency_code` string, required — Currency code (ISO 4217)
        - `value` number, required — Payment total amount
      - `provider_reference` object — Provider reference data
        - `order_id` string — Provider order identifier, used to identify the order in the acquirer
        - `payment_id` string — Provider payment identifier, used to identify the payment in the acquirer. (Mandatory data when the payment is Collected)
        - `batch_id` string — Batch identifier from the acquirer (optional)
        - `ticket_number` string — Ticket number from the acquirer (optional)
        - `tid` string — Transaction identifier from the acquirer (optional)
        - `nsu` string — NSU (Número Sequencial Único) from the acquirer (optional)
    - `order_id` string — Order ID returned by create payment service
    - `status` object, required
      - `type` string, required — Payment status.
      - `date` string, date-time, required — Status change date (ISO 8601 date format)
      - `expiration` string, date-time — Status expiration date (ISO 8601 date format)
      - `reason` string — Payment status reason
      - `error` StatusError — Error details. Present when the payment failed and error information is available.
        - `code` string — Error code.
        - `message` string — Error message.
    - `payment_method` object, required
      - `code` 'CARD', required — Payment method code.
      - `installments` number, required — Installments of the payment
    - `payer` object
      - `document` object
        - `type` 'cpf' | 'cnpj', required — Payer document type (cpf, cnpj)
        - `number` string, required — Payer document number
      - `phone` object
        - `area` string, required — Phone area code
        - `number` string, required — Phone number
    - `refunds` RefundDetailResponse[] — Refunds data
      - `id` string, required — Unique refund identifier.
      - `amount` object, required
        - `currency_code` string, required — Currency code (ISO 4217)
        - `value` number, required — Refund total amount
      - `status` StatusRefund, required
        - `type` 'Refunded' | 'InProgress' | 'Failed', required — Payment status.
        - `date` string, date-time, required — Status change date (ISO 8601 date format)
        - `error` StatusError — Error details. Present when the payment failed and error information is available.
          - `code` string — Error code.
          - `message` string — Error message.
      - `code` string — Standardized error code (applies only for error cases)
      - `message` string — Message associated with the error code (applies only for error cases)
      - `causes` string[] — List of strings that details the cause that generates the error.
    - `antifraud` object
      - `type` 'Approved' | 'Denied' | 'Received' | 'Undefined', required — Antifraud status.
      - `date` string, date-time, required — Antifraud status date (ISO 8601 date format)
    - `code` string — Standardized error code (applies only for error cases)
    - `message` string — Message associated with the error code

## Other responses

- `400` — Bad Request
- `404` — Not Found
- `500` — Internal Server Error

---

[API](https://skmtc.dev/koin/apis/payments-api.md) · [All operations](https://skmtc.dev/koin/apis/payments-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/koin/payments-api/revisions/6f2c01e43fe2/schema)