Reach GET API

openapi: 3.2.0
info:
  version: '2.22'
  title: Reach Checkout GET API
  contact:
    email: support@withreach.com
  description: 'June 2022

    withreach.com

    docs.withreach.com


    Reach''s Checkout API provides suppliers the ability to execute and manage payment processing for consumer orders while retaining control over the shopper experience and limiting PCI DSS exposure. Creating payment orders, refunding payments, and querying available foreign exchange rates and payment methods are all provided by this JSON-based API.'
servers:
- description: Reach Sandbox
  url: https://checkout.rch.how/v2.22
- description: Reach Dev
  url: https://checkout.rch.red/v2.22
tags:
- name: Get
paths:
  /badge:
    get:
      operationId: badge
      description: Retrieve location declaration information from Reach. For more information see Reach disclaimer and Terms of Service requirements.
      parameters:
      - name: MerchantId
        in: query
        description: 'The 36 character GUID which identifies the supplier to the Reach system.

          '
        required: true
        schema:
          description: 'The 36 character GUID which identifies the supplier to the Reach system.

            '
          type: string
          format: uuid
      - name: Locale
        in: query
        description: 'The specified Locale code to translate the badge. If no Locale is specified, we will default to English (US). For Locale options, please see information here: https://docs.withreach.com/docs/request-format.

          '
        required: false
        schema:
          description: JSONP Javascript function name.
          type: string
      - name: Callback
        in: query
        description: The JSONP Javascript function to call.
        schema:
          description: JSONP Javascript function name.
          type: string
      - name: Currency
        in: query
        description: 'If the consumer currency to be used is already known, the upper-case 3 character ISO 4217 currency code.

          '
        schema:
          description: An upper-case 3 character ISO 4217 currency code.
          type: string
          pattern: ^[A-Z]{3}$
      - name: ConsumerIpAddress
        in: query
        description: 'This parameter can be specified if the request is being made on behalf of the consumer, not directly via the consumer''s browser.

          '
        schema:
          description: A valid IP address, v4 or v6.
          oneOf:
          - type: string
            format: ipv4
          - type: string
            format: ipv6
      - name: Theme
        in: query
        description: 'The logo and html returned by badge will be themed based on this  parameter’s value. This parameter can be set to **light** or **dark**.  Defaults to the light theme.

          '
        schema:
          type: string
          enum:
          - light
          - dark
      responses:
        '200':
          description: 'Either the text or image should be displayed and linked to the  TermsOfServiceUrl.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  Text:
                    description: The text to display.
                    type: string
                  Html:
                    description: The HTML snippet to display.
                    type: string
                  ImageUrl:
                    description: The image to display.
                    type: string
                    format: uri
                  TermsOfServiceUrl:
                    description: The location that the text or image should link to.
                    type: string
                    format: uri
                  MerchantOfRecord:
                    description: The name of the entity handling the payment.
                    type: string
                  MerchantOfRecordUrl:
                    description: The location of the Merchant of Record website.
                    type: string
                    format: uri
                  MerchantName:
                    description: 'As a convenience, the name of the supplier associated with the specified MerchantId.

                      '
                    type: string
                  FlagImageUrl:
                    description: The flag image associated with the Merchant of Record.
                    type: string
                required:
                - Text
                - Html
                - ImageUrl
                - TermsOfServiceUrl
                - MerchantOfRecord
                - MerchantOfRecordUrl
                - MerchantName
                - FlagImageUrl
        '400':
          description: 'If present, the badge request structure was invalid and unable to be parsed.

            '
        '404':
          description: 'If present, a value of the request was unable to be found. For example, if the MerchantId provided could not be found in the given environment

            '
        '503':
          description: 'There was a system problem and the request should be tried again.

            '
      tags:
      - Get
      summary: Badge
      x-summary-source: derived
  /fingerprint:
    get:
      operationId: fingerprint
      description: Collect a device fingerprint from the shopper's browser via an HTML script tag. For more details, please refer to https://docs.withreach.com/docs/fingerprint.
      parameters:
      - name: MerchantId
        in: query
        description: 'The 36 character GUID which identifies the supplier to the Reach system.

          '
        required: true
        schema:
          description: 'The 36 character GUID which identifies the supplier to the Reach system.

            '
          type: string
          format: uuid
      responses:
        '200':
          description: 'The script tag returns Javascript that both inserts device detection HTML into the DOM and sets a global Javascript variable (gip_device_fingerprint) that is utilized in the checkout request.

            '
          content:
            text/javascript; charset=utf-8:
              schema:
                type: string
        '400':
          description: 'If present, the fingerprint request structure was invalid and unable to be parsed.

            '
        '404':
          description: 'If present, a value of the request was unable to be found. For example, if the MerchantId provided could not be found in the given environment

            '
        '503':
          description: 'There was a system problem and the request should be tried again.

            '
      tags:
      - Get
      summary: Fingerprint
      x-summary-source: derived
  /getCardInfo:
    get:
      operationId: getCardInfo
      description: Fetches information about a card based on its IIN.
      parameters:
      - name: MerchantId
        in: query
        description: 'The 36 character GUID which identifies the supplier to the Reach system.

          '
        required: true
        schema:
          description: 'The 36 character GUID which identifies the supplier to the Reach system.

            '
          type: string
          format: uuid
      - name: IIN
        in: query
        description: 'The 8-digit IIN (Issuer Identification Number) of the card. Previously known as the BIN, this is the first 8 digits of the card for which info should be fetched. Only values between 10000000 and 99999999 are accepted.

          '
        required: true
        schema:
          description: 'The 8-digit IIN (Issuer Identification Number) of the card. Previously known as the BIN, this is the first 8 digits of the card for which info should be fetched. Only values between 10000000 and 99999999 are accepted.

            '
          type: integer
          maximum: 99999999
          minimum: 10000000
          pattern: ^[1-9]{1}[0-9]{5}$
      - name: Callback
        in: query
        description: The JSONP Javascript function to call.
        schema:
          description: JSONP Javascript function name.
          type: string
      responses:
        '200':
          description: 'Information about the card was successfully retrieved.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  IIN:
                    description: 'The 8-digit IIN (Issuer Identification Number) of the card. Previously known as the BIN, this is the first 8 digits of the card for which info should be fetched. Only values between 10000000 and 99999999 are accepted.

                      '
                    type: integer
                    maximum: 99999999
                    minimum: 10000000
                    pattern: ^[1-9]{1}[0-9]{5}$
                  PaymentMethod:
                    description: The Reach payment method associated with this IIN.
                    type: string
                  Type:
                    description: If known, this will be either Credit or Debit.
                    type: string
                    enum:
                    - Credit
                    - Debit
                  PrePaid:
                    description: 'If known, a flag indicating if the card is a pre-paid card.

                      '
                    type: boolean
                  IssuingCountry:
                    description: 'If known, the country from which the card was issued.

                      '
                    type: string
                    pattern: ^[A-Z]{2}$
                  Available:
                    description: 'If false, this is a known IIN, but cannot be processed via Reach.

                      '
                    type: boolean
                required:
                - IIN
                - PaymentMethod
        '400':
          description: 'If present, the getCardInfo request structure was invalid and unable to be parsed.

            '
        '404':
          description: 'If present, a value of the request was unable to be found. For example, if the MerchantId provided could not be found in the given environment

            '
        '503':
          description: 'There was a system problem and the request should be tried again.

            '
      tags:
      - Get
      summary: Get card info
      x-summary-source: derived
  /getPaymentMethods:
    get:
      operationId: getPaymentMethods
      description: Retrieve available payment methods for the specified currency and country.
      parameters:
      - name: MerchantId
        in: query
        description: 'The 36 character GUID which identifies the supplier to the Reach system.

          '
        required: true
        schema:
          description: 'The 36 character GUID which identifies the supplier to the Reach system.

            '
          type: string
          format: uuid
      - name: Country
        in: query
        description: 'Upper-case 2 character ISO 3166-1-alpha-2 country code. Only methods available to this country will be returned.

          '
        required: true
        schema:
          description: An upper-case ISO 3166 alpha-2 country code.
          type: string
          pattern: ^[A-Z]{2}$
      - name: Currency
        in: query
        description: 'Upper-case 3 character ISO 4217 currency code. Only methods available to this currency will be returned.

          '
        required: true
        schema:
          description: An upper-case 3 character ISO 4217 currency code.
          type: string
          pattern: ^[A-Z]{3}$
      - name: ViaAgent
        in: query
        description: 'If true, only payment methods able to be completed via an agent will be returned.

          '
        schema:
          type: boolean
      - name: Callback
        in: query
        description: The JSONP Javascript function name.
        schema:
          description: JSONP Javascript function name.
          type: string
      responses:
        '200':
          description: 'The payment methods available to this customer was successfully retrieved.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  PaymentMethods:
                    description: 'An array containing information about the payment methods available to the specified Country and Currency (and possibly the ViaAgent flag)

                      '
                    type: array
                    items:
                      type: object
                      required:
                      - Id
                      - Name
                      - Class
                      - Language
                      properties:
                        Id:
                          description: 'The Reach canonical name of the payment method.

                            '
                          type: string
                        Name:
                          description: 'The industry accepted name of the payment method. For example: ''MasterCard''

                            '
                          type: string
                        Local:
                          description: 'If present and true, this payment method is considered local to the country specified in the request and may have better conversion if presented prominently to the shopper.

                            '
                          type: boolean
                        Class:
                          description: 'The class of the payment method will be one of the following:<br> **Card** - (ex: VISA, MC)<br> **Offline** - (ex: BOLETO, BANK)<br> **Online** - (ex: PAYPAL, EFT)

                            '
                          type: string
                          enum:
                          - Card
                          - Offline
                          - Online
                        Language:
                          description: 'The associated language of translation for the payment method name in ISO 639-1 format (default English).

                            '
                          type: string
                          pattern: '[a-z]{2}'
                        Parameters:
                          description: 'The Klarna-specific parameters used for On-Site Message platform.

                            '
                          type: object
                          properties:
                            ClientId:
                              description: On-Site Messaging Client Identifier.
                              type: string
                              format: uuid
                            OnSiteJavaScriptUrl:
                              description: On-Site Messaging script url.
                              type: string
                              format: uri
                        Financing:
                          description: 'If present and true, financing options (detailed below) are available if payment is made using this method.

                            '
                          type: boolean
                        Issuers:
                          description: 'An array of issuers that may be associated with this payment method. Typically, these identify banks or other institutions that issue payment products. If present, an issuer must be selected from this list to use this payment method.

                            '
                          type: array
                          items:
                            type: object
                            required:
                            - Id
                            - Name
                            properties:
                              Id:
                                description: 'The Reach canonical name of the issuer. For example: ''AhorroFamsa''

                                  '
                                type: string
                              Name:
                                description: 'A human-readable name for the issuer. For example: ''Banco Ahorro Famsa''.

                                  '
                                type: string
                  Financing:
                    description: 'If financing options are available for any of the payment methods returned, the options will be listed here.

                      '
                    type: object
                    properties:
                      Instalments:
                        description: 'The financing information associated with payment via instalments.

                          '
                        type: array
                        items:
                          type: object
                          required:
                          - Number
                          - Rate
                          properties:
                            Number:
                              description: 'The number of instalments in which the payment will be made.

                                '
                              type: integer
                            Rate:
                              description: 'The rate by which the total amount, excluding financing, should be multiplied to determine the financing fees.

                                '
                              type: number
                              format: double
                required:
                - PaymentMethods
        '400':
          description: 'If present, the getPaymentMethods request structure was invalid and unable to be parsed.

            '
        '404':
          description: 'If present, a value of the request was unable to be found. For example, if the MerchantId provided could not be found in the given environment

            '
        '503':
          description: 'There was a system problem and the request should be tried again.

            '
      tags:
      - Get
      summary: Get payment methods
      x-summary-source: derived
  /getRate:
    get:
      operationId: getRate
      description: Fetches information about a single rate offer. This will return information about the rate offer so long as it exists, even if it has expired.
      parameters:
      - name: MerchantId
        in: query
        description: 'The 36 character GUID which identifies the supplier to the Reach system.

          '
        required: true
        schema:
          description: 'The 36 character GUID which identifies the supplier to the Reach system.

            '
          type: string
          format: uuid
      - name: RateOfferId
        in: query
        description: 'A Reach rate offer ID for the supplier.

          '
        required: true
        schema:
          type: string
          format: uuid
      - name: Callback
        in: query
        description: The JSONP Javascript function to call.
        schema:
          description: JSONP Javascript function name.
          type: string
      responses:
        '200':
          description: 'Rate information was successfully retrieved.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  Id:
                    description: A Reach rate offer ID for the supplier.
                    type: string
                    format: uuid
                  Currency:
                    description: 'The upper-case 3 character ISO 4217 currency code for this rate offer.

                      '
                    type: string
                    pattern: ^[A-Z]{3}$
                  Expiry:
                    description: 'The RFC 3339 timestamp at which this rate offer expires.

                      '
                    type: string
                    format: date-time
                  Rate:
                    description: The Reach guaranteed exchange rate.
                    type: number
                    format: double
                required:
                - Id
                - Currency
                - Expiry
                - Rate
        '400':
          description: 'If present, the getRate request structure was invalid and unable to be parsed.

            '
        '404':
          description: 'If present, a value of the request was unable to be found. For example, if the MerchantId provided could not be found in the given environment

            '
        '503':
          description: 'There was a system problem and the request should be tried again.

            '
      tags:
      - Get
      summary: Get rate
      x-summary-source: derived
  /getRates:
    get:
      operationId: getRates
      description: 'Fetches the list of current foreign exchange rate offers that are available to the supplier.


        The returned foreign exchange rates are only guaranteed up to the expiry time specified— typically 24 hours. Attempting to create an order using an expired foreign exchange rate will result in an error. To avoid confusion it is recommended to call getRates several times per day.'
      parameters:
      - name: MerchantId
        in: query
        description: 'The 36 character GUID which identifies the supplier to the Reach system.

          '
        required: true
        schema:
          description: 'The 36 character GUID which identifies the supplier to the Reach system.

            '
          type: string
          format: uuid
      - name: Callback
        in: query
        description: The JSONP Javascript function to call.
        schema:
          description: JSONP Javascript function name.
          type: string
      responses:
        '200':
          description: 'Rates information was successfully retrieved.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  RateOffers:
                    description: 'An array of rate offers, if guaranteed rates are available.

                      '
                    type: array
                    items:
                      type: object
                      required:
                      - Id
                      - Currency
                      - Expiry
                      - Rate
                      properties:
                        Id:
                          description: 'A Reach rate offer ID for the supplier that can be used until the specified Expiry.

                            '
                          type: string
                          format: uuid
                        Currency:
                          description: 'The upper-case 3 character ISO 4217 currency code for this rate offer.

                            '
                          type: string
                          pattern: ^[A-Z]{3}$
                        Expiry:
                          description: 'The RFC 3339 timestamp at which this rate offer expires.

                            '
                          type: string
                          format: date-time
                        Rate:
                          description: The Reach guaranteed exchange rate.
                          type: number
                          format: double
                  Rates:
                    description: 'An array of non-guaranteed market rates that are returned if spot rates are enabled and guaranteed rates are not enabled.

                      '
                    type: array
                    items:
                      type: object
                      required:
                      - Currency
                      - Rate
                      properties:
                        Currency:
                          description: 'The upper-case 3 character ISO 4217 currency code for this rate offer.

                            '
                          type: string
                          pattern: ^[A-Z]{3}$
                        Rate:
                          description: 'The approximate market exchange rate, updated regularly.

                            '
                          type: number
                          format: double
        '400':
          description: 'If present, the getRates request structure was invalid and unable to be parsed.

            '
        '404':
          description: 'If present, a value of the request was unable to be found. For example, if the MerchantId provided could not be found in the given environment

            '
        '503':
          description: 'There was a system problem and the request should be tried again.

            '
      tags:
      - Get
      summary: Get rates
      x-summary-source: derived
  /localize:
    get:
      operationId: localize
      description: Retrieve locale data from Reach.
      parameters:
      - name: MerchantId
        in: query
        description: 'The 36 character GUID which identifies the supplier to the Reach system.

          '
        required: true
        schema:
          description: 'The 36 character GUID which identifies the supplier to the Reach system.

            '
          type: string
          format: uuid
      - name: Callback
        in: query
        description: The JSONP Javascript function name.
        schema:
          description: JSONP Javascript function name.
          type: string
      - name: Country
        in: query
        description: 'If the supplier already knows the consumer''s country, the ISO3166-1-alpha-2 can be passed in to fetch the localization data for that country. If this is specified, the GEO-IP lookup will be bypassed.

          '
        schema:
          description: An upper-case ISO 3166 alpha-2 country code.
          type: string
          pattern: ^[A-Z]{2}$
      - name: Currency
        in: query
        description: 'The upper-case 3 character ISO 4217 currency code to get the symbol and units for, if available.

          '
        schema:
          description: An upper-case 3 character ISO 4217 currency code.
          type: string
          pattern: ^[A-Z]{3}$
      - name: IncludeRate
        in: query
        description: 'If true, the latest rate offer will be returned.  If not included, or false, a rate offer will not be returned.

          '
        schema:
          type: boolean
      - name: ConsumerIpAddress
        in: query
        description: 'This parameter must be specified when the request is being made on behalf of the consumer, not directly via the consumer''s browser. If a Country is specified, this is ignored.

          '
        schema:
          description: A valid IP address, v4 or v6.
          oneOf:
          - type: string
            format: ipv4
          - type: string
            format: ipv6
      - name: MerchantPrices
        in: query
        description: 'If the supplier is configured to use Reach''s Vanity Pricing, a set of tags and associated prices.

          '
        schema:
          type: array
          items:
            type: object
            required:
            - Price
            properties:
              Price:
                description: The price to convert.
                type: number
                format: double
              Tag:
                description: 'A tag associated with the price. This may be a SKU, ID, group,etc.

                  '
                type: string
      responses:
        '200':
          description: 'Locale information was able to be retrieved.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  Country:
                    description: 'The ISO 3166-1-alpha-2 country code specified in the request, or determined by GEO-IP lookup, or null if it could not be  determined.

                      '
                    type: string
                    pattern: ^[A-Z]{2}$
                  Currency:
                    description: 'The upper-case 3 character ISO 4217 currency code for the default currency for the country, unless Currency was specified.  The currency, and the associated information below, will only be returned if supported by Reach.

                      '
                    type: string
                    pattern: ^[A-Z]{3}$
                  Symbol:
                    description: 'The symbol for the currency, if applicable (e.g. $, £, Kč).

                      '
                    type: string
                  Units:
                    description: 'Returned only if a Currency is returned. The number of minor units to display for the currency. Note that up to two decimal places may be specified to checkout.

                      '
                    type: integer
                    maximum: 2
                    minimum: 0
                  RateOffer:
                    description: 'Returned only if a Currency is returned and IncludeRate is true. The current rate offer available for specified currency.

                      '
                    type: object
                    properties:
                      Id:
                        description: 'A Reach rate offer ID for the supplier that can be used until the specified Expiry.

                          '
                        type: string
                        format: uuid
                      Expiry:
                        description: 'The RFC 3339 timestamp at which this rate offer expires.

                          '
                        type: string
                        format: date-time
                      Rate:
                        description: The Reach guaranteed exchange rate.
                        type: number
                        format: double
                    required:
                    - Id
                    - Expiry
                    - Rate
                  Rate:
                    description: 'Returned only if a Currency is returned and IncludeRate is true. The current non-guaranteed market rate for the specified currency, if spot rates are enabled and guaranteed rates are not enabled.

                      '
                    type: number
                    format: double
                  ConsumerPrices:
                    description: 'An array of prices in the requested currency, in the same  order as the MerchantPrices specified in the request.

                      '
                    type: array
                    items:
                      type: number
                      format: double
        '400':
          description: 'If present, the localize request structure was invalid and unable to be parsed.

            '
        '404':
          description: 'If present, a value of the request was unable to be found. For example, if the MerchantId provided could not be found in the given environment

            '
        '503':
          description: 'There was a system problem and the request should be tried again.

            '
      tags:
      - Get
      summary: Localize
      x-summary-source: derived
x-explorer-enabled: false
x-samples-enabled: false
x-provenance:
  method: searched
  source: https://docs.withreach.com/reference
  harvested: '2026-10-28'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.withreach.com/reference/badge.md
  - https://docs.withreach.com/reference/cancel.md
  - https://docs.withreach.com/reference/capture.md
  - https://docs.withreach.com/reference/checkout.md
  - https://docs.withreach.com/reference/fingerprint-1.md
  - https://docs.withreach.com/reference/getcardinfo.md
  - https://docs.withreach.com/reference/getpaymentmethods.md
  - https://docs.withreach.com/reference/getrate.md
  - https://docs.withreach.com/reference/getrates.md
  - https://docs.withreach.com/reference/listreports.md
  - https://docs.withreach.com/reference/localize.md
  - https://docs.withreach.com/reference/modify.md
  - https://docs.withreach.com/reference/opencontract.md
  - https://docs.withreach.com/reference/query.md
  - https://docs.withreach.com/reference/refund.md
  merge:
    pages: 15
    deduped: 0
    conflicts_kept_first: 0