---
title: "Direct Integration"
source_url: https://docs.rapyd.net/en/direct-integration.html
lang: en
---

# Direct Integration

## *Disclaimer*

*Beta-stage product. This solution is in the beta stage and therefore considered a Beta-stage product. It is clarified that if there are any faults and/or issues, it will not affect your obligation to provide us with the requested and accurate information and documentation. This information should be delivered with no dependency on the stability and performance of the product. If the product is not working as expected, you should use any other alternative to fulfill your obligations as described above.*

## Introduction

This document demonstrates how to define Rapyd’s API calls in order to integrate physical card payments (‘card present’) in a payment device, and serves as the baseline for all future card-present integrations with the Rapyd API.

### Intended Audience

The document is intended for developers who have a basic understanding of the following:

- REST APIs that request and receive data in the JSON (JavaScript Object Notation) format.
- Running REST API methods on Postman or integrating these methods in any programming language.

## Required Headers

All requests must include the following headers:

- access_key - Unique access key provided by Rapyd for each authorized user. Required. For more information, see [Developers](https://docs.rapyd.net/en/developers.html).
- api_version - see [Versioning for API Methods](https://docs.rapyd.net/en/versioning-for-api-methods.html).
- Content-Type - Indicates that the data appears in JSON format. Required. Set to **application/json** unless the request is for uploading a file.
- idempotency - A unique string to protect against duplicate transactions. Optional. For more information, see [Idempotency](https://docs.rapyd.net/en/idempotency.html).
- salt - Salt for the request signature. A random string for each request. Recommended length: 8-16 digits, letters and special characters. Required.
- signature - Signature calculated for each message individually. Required. For REST requests, see [Request Signatures](https://docs.rapyd.net/en/request-signatures.html). For webhooks, see [Webhook Authentication](https://docs.rapyd.net/en/webhook-authentication.html).
- timestamp - The time of the request, in [Unix time](https://docs.rapyd.net/en/glossary.html#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time) (seconds). Required.

Server List

| URL | Description |
| --- | --- |
| **base_url:** The URL of the server.  For example, `https://sandboxapi.rapyd.net/v1` | Rapyd’s sandbox environment. |

> **Note:**
>
> - Currently only available in Rapyd’s sandbox environment.
> - The merchant must also be subscribed to receive related webhooks to their defined server address.

## Step 1: Get Payment Method Required Fields

Retrieve a list of all the required fields for one of the following supported payment methods:

- `is_mastercard_pos`
- `is_visa_pos`
- `is_amex_pos`

|  |
| --- |
| **Endpoint:**  `GET{base_url}/payment_methods/required_fields/is_mastercard_pos`  Or  `GET{base_url}/payment_methods/required_fields/is_visa_pos`  Or  `GET{base_url}/payment_methods/required_fields/is_amex_pos` |

**Response Parameters:** Includes the following parameters in the `fields` o

ebject:

| Response Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `expiration_month` | Yes | String | Expiration month as a two digit string: 01-12 |
| `expiration_year` | Yes | String | Expiration year in two digits as a string: 26-99 |
| `icc_data` | No | String | A list of TLV (tag-length-value) sets. The following tags must be filtered out: Tag 57 (EMV track 2 equivalent data), Tag 5F24 (Application Expiration Date), Tag 5F34 (Pan Sequence Number), and Tag 5A (Application Primary Account Number). A null value is valid in certain scenarios. |
| `number` | Yes | String | Card number. |
| `number_type` | No | String | Determines if the number is funding PAN or token PAN. Valid values are **fpan** or **tpan**. |
| `pin_block` | No | String | Encrypted PIN block in hexadecimal format. Required only if `pin_block_key_index` is provided. |
| `pin_block_key_index` | No | String | Partner key index as provided by Rapyd, Required if `pin_block` is provided. |
| `pin_block_key_serial` | No | String | Key serial number (KSN) supplied by the PIN pad. Used with base derived keys (BDK). |
| `single_tap_follow_up` | No | Boolean | Indicates whether this is a follow-up single tap transaction.  - **0** - Not a follow-up. Default. - **1** - Follow-up. |
| `single_tap_supported` | No | Boolean | Indicates whether a single tap is supported.  - **0** - Not supported. Default. - **1** - Supported. |
| `soft_pos_information` | No | string | Contains information about the device and software used in SoftPOS transactions. |
| `terminal_capability` | No | String | Terminal capability.  - **8** - Contactless only. |
| `terminal_pin_entry_capability` | No | String | Terminal PIN entry capability.  - **0** - Unknown - **1** - PIN entry capability - **2** - No PIN entry capability - **3** - Software PIN entry capability - **8** - PIN entry capability but PIN pad is not functioning. |
| `terminal_type` | No | string | Terminal type.  - **3** - Unattended terminal. - **9** - mPOS device - **10 -** Off-the-shelf mobile device. |
| `track2_data` | No | String | Contains the contents of EMV tag 57 with any trailing filler 'F' characters removed. A null value is valid in certain scenarios. |

The `payment_method_options` object includes the following fields:

| `payment_method_options` Response Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `sca_exemption` | No | String | Request a strong customer authentication (SCA) exemption from 3D Secure (3DS) authentication for a merchant of a payment facilitator (PayFac). Specify one exemption type. To enable this feature, contact Rapyd Client Support. Supported values:  - **low_value** - **transaction_risk_analysis** - **authentication_outage** - **secure_corporate_payments** |

The `payment_options` object includes the following fields:

| `payment_options` Response Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `capture` | No | Boolean | Determines when the payment is processed for capture. |
| `device_id` | Yes | string | A unique id that is assigned by the POS provider and applies to their device. Note that even though a particular device belongs to a certain merchant and for a certain payment, it might be sending transactions for a different merchant in the future. |
| `ewallet` | Yes | String | ID of the wallet that the money is paid into. String starting with **ewallet_.** |
| `initiation_type` | No | String | Indicates how the transaction was initiated. One of the following values:  - **card_present** - **customer_present** - **installment** - **moto** - **recurring** - **unscheduled** |
| `payment_advice` | Yes | Object | An JSON object containing information from the incoming POS device that has not already been mapped to other fields in the payment. |
| `statement_descriptor` | No | String | A text description suitable for a customer's payment statement. 5-22 characters. |

Sample: Get `is_visa_pos` Payment Method Required Fields

- - Request

    - ```curl
      curl -X GET https://sandboxapi.rapyd.net/v1/payment_methods/required_fields/is_visa_pos
      -H 'access_key: your-access-key-here' \
      -H 'Content-Type: application/json' \
      -H 'salt: your-random-string-here' \
      -H 'signature: your-calculated-signature-here' \
      -H 'timestamp: your-unix-timestamp-here'
      ```
- - Response

    - ```json
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "e7dcbb93-1aa2-45ce-8c1c-6e5556929953"
          },
          "data": {
              "type": "is_visa_pos",
              "fields": [
                  {
                      "name": "number",
                      "type": "string",
                      "regex": "",
                      "is_required": true,
                      "instructions": "card number"
                  },
                  {
                      "name": "number_type",
                      "type": "string",
                      "regex": "(fpan|tpan)",
                      "description": "Determining if number is funding PAN or token PAN",
                      "is_required": false
                  },
                  {
                      "name": "expiration_month",
                      "type": "string",
                      "regex": "",
                      "is_required": true,
                      "instructions": "Expiration month as string, 01-12"
                  },
                  {
                      "name": "expiration_year",
                      "type": "string",
                      "regex": "",
                      "is_required": true,
                      "instructions": "Expiration year in to digits as string, 18-99"
                  },
                  {
                      "name": "pin_block",
                      "type": "string",
                      "regex": "^[A-Fa-f0-9]{16}$",
                      "description": "Encrypted PIN block in hexadecimal format. Required if 'pin_block_key_index' is provided.",
                      "is_required": false
                  },
                  {
                      "name": "pin_block_key_index",
                      "type": "string",
                      "regex": "^[0-9]{1,4}$",
                      "description": "Partner key index as provided by Rapyd, Required if 'pin_block' is provided.",
                      "is_required": false
                  },
                  {
                      "name": "pin_block_key_serial",
                      "type": "string",
                      "regex": "^[A-Fa-f0-9]{1,20}$",
                      "description": "Key serial number (KSN) supplied by the PIN pad. Used with base derived keys (BDK).",
                      "is_required": false
                  },
                  {
                      "name": "single_tap_supported",
                      "type": "boolean",
                      "regex": "",
                      "description": "Indicates whether a single tap is supported. 0 = Not supported, 1 = Supported. Default: false.",
                      "is_required": false
                  },
                  {
                      "name": "single_tap_follow_up",
                      "type": "boolean",
                      "regex": "",
                      "description": "Indicates whether this is a follow-up single tap transaction. 0 = Not a follow-up, 1 = Follow-up. Default: false.",
                      "is_required": false
                  },
                  {
                      "name": "soft_pos_information",
                      "type": "string",
                      "regex": "^[A-Za-z0-9\\(\\)\\.\\+\\,\\-]*$",
                      "description": "Contains information about the device and software used in SoftPOS transactions.",
                      "is_required": false
                  },
                  {
                      "name": "terminal_type",
                      "type": "string",
                      "regex": "^(3|9|10)$",
                      "description": "Terminal type. 3 = Unattended terminal, 9 = mPOS device, 10 = Off-the-shelf mobile device.",
                      "is_required": false
                  },
                  {
                      "name": "terminal_capability",
                      "type": "string",
                      "regex": "^8$",
                      "description": "Terminal capability. 8 = Contactless only.",
                      "is_required": false
                  },
                  {
                      "name": "terminal_pin_entry_capability",
                      "type": "string",
                      "regex": "^(0|1|2|3|8)$",
                      "description": "Terminal PIN entry capability. 0 = Unknown, 1 = PIN entry capability, 2 = No PIN entry capability, 3 = Software PIN entry capability, 8 = PIN entry capability but PIN pad down.",
                      "is_required": false
                  },
                  {
                      "name": "track2_data",
                      "type": "string",
                      "regex": "",
                      "description": "Track2 data",
                      "is_required": false
                  },
                  {
                      "name": "icc_data",
                      "type": "string",
                      "regex": "",
                      "description": "ICC data",
                      "is_required": false
                  }
              ],
              "payment_method_options": [
                  {
                      "name": "sca_exemption",
                      "type": "string",
                      "regex": "(low_value|transaction_risk_analysis|authentication_outage|secure_corporate_payments)",
                      "description": "Request a strong customer authentication (SCA) exemption from 3D Secure (3DS) authentication for a merchant of a payment facilitator (PayFac). Specify one exemption type. To enable this feature, contact Rapyd Client Support.",
                      "is_required": false,
                      "is_updatable": false
                  }
              ],
              "payment_options": [
                  {
                      "name": "capture",
                      "type": "boolean",
                      "regex": "",
                      "description": "Determines when the payment is processed for capture.",
                      "is_required": false,
                      "is_updatable": false
                  },
                  {
                      "name": "statement_descriptor",
                      "type": "string",
                      "regex": "",
                      "description": "A text description suitable for a customer's payment statement. 5-22 characters.",
                      "is_required": true,
                      "is_updatable": false
                  },
                  {
                      "name": "ewallet",
                      "type": "string",
                      "regex": "^ewallet_[a-f0-9]{32}$",
                      "description": "ID of the wallet that the money is paid into. String starting with ewallet_.",
                      "is_required": true,
                      "is_updatable": false
                  },
                  {
                      "name": "initiation_type",
                      "type": "string",
                      "regex": "(card_present|customer_present|installment|moto|recurring|unscheduled)",
                      "description": "This indicates how the transaction was initiated.",
                      "is_required": false,
                      "is_updatable": false
                  },
                  {
                      "name": "device_id",
                      "type": "string",
                      "regex": "",
                      "description": "A unique id that is assigned by the POS provider and applies to his device. Note that even though a particular device belongs to a certain merchant today and for a certain payment, it might be sending transactions for a different merchant tomorrow.",
                      "is_required": true,
                      "is_updatable": false
                  },
                  {
                      "name": "payment_advice",
                      "type": "object",
                      "regex": "",
                      "description": "A json field containing information from the incoming pos device that has not already been mapped to other fields in the payment/pmt.",
                      "is_required": true,
                      "is_updatable": false
                  }
              ],
              "minimum_expiration_seconds": 0,
              "maximum_expiration_seconds": 2592000
          }
      }
      ```

The response includes the fields of the `is_visa_pos` payment method.

## Step 2: Create Payment

Create a payment with the required payment method fields that were determined by running the [Get Payment Method Required Fields](https://docs.rapyd.net/en/get-payment-method-required-fields.md "Get Payment Method Required Fields") API call.

|  |
| --- |
| **Endpoint****:** `POST{base_url}/payments` |

**Body Parameters:**

| Body Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `amount` | Yes | number | The amount of the payment, in units of the currency defined in currency. Decimal, including the correct number of decimal places for the currency exponent, as defined in ISO 4217:2015. To verify a card, set to 0. |
| `currency` | Yes | string | Defines the currency of the transaction. Three-letter ISO 4217 code. |

The following fields in the `payment_method` object:

| `payment_method` Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `type` | Yes | string | Name of the payment method type. One of the following:  - `is_mastercard_pos` - `is_visa_pos` - `is_amex_pos` |
| `fields` | Yes | Object | Contains the fields that are required for the payment method. Optional fields may also be included. See complete list in the table below. |

The following fields in the `fields` object:

| `fields` Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `expiration_month` | Yes | String | Expiration month as a two digit string: 01-12 |
| `expiration_year` | Yes | String | Expiration year in two digits as a string: 26-99 |
| `icc_data` | No | String | A list of TLV (tag-length-value) sets. The following tags must be filtered out: Tag 57 (EMV track 2 equivalent data), Tag 5F24 (Application Expiration Date), Tag 5F34 (Pan Sequence Number), and Tag 5A (Application Primary Account Number). A null value is valid in certain scenarios. |
| `number` | Yes | String | Card number. |
| `number_type` | No | String | Determines if the number is funding PAN or token PAN. Valid values are **fpan** or **tpan**. |
| `pin_block` | No | String | Encrypted PIN block in hexadecimal format. Required only if `pin_block_key_index` is provided. |
| `pin_block_key_index` | No | String | Partner key index as provided by Rapyd, Required if `pin_block` is provided. |
| `pin_block_key_serial` | No | String | Key serial number (KSN) supplied by the PIN pad. Used with base derived keys (BDK). |
| `single_tap_follow_up` | No | Boolean | Indicates whether this is a follow-up single tap transaction.  - **0** - Not a follow-up. Default - **1** - Follow-up. |
| `single_tap_supported` | No | Boolean | Indicates whether a single tap is supported.  - **0** - Not supported. Default. - **1** - Supported. |
| `soft_pos_information` | No | string | Contains information about the device and software used in SoftPOS transactions. |
| `terminal_capability` | No | String | Terminal capability.  - . **8** - Contactless only. |
| `terminal_pin_entry_capability` | No | String | Terminal PIN entry capability.  - **0** - Unknown - **1** - PIN entry capability - **2** - No PIN entry capability - **3** - Software PIN entry capability - **8** - PIN entry capability but PIN pad is not functioning. |
| `terminal_type` | No | string | Terminal type.  - **3** - Unattended terminal - **9** - mPOS device - **10** - Off-the-shelf mobile device. |
| `track2_data` | No | String | Contains the contents of EMV tag 57 with any trailing filler 'F' characters removed. A null value is valid in certain scenarios. |

The `payment_options` object includes the following fields:

| `payment_options` Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `capture` | No | Boolean | Determines when the payment is processed for capture. |
| `device_id` | Yes | string | A unique id that is assigned by the POS provider and applies to their device. Note that even though a particular device belongs to a certain merchant and for a certain payment, it might be sending transactions for a different merchant in the future. |
| `ewallet` | Yes | String | ID of the wallet that the money is paid into. String starting with **ewallet_.** |
| `initiation_type` | No | String | Indicates how the transaction was initiated. One of the following values:  - **card_present** - **customer_present** - **installment** - **moto** - **recurring** - **unscheduled** |
| `payment_advice` | Yes | Object | An JSON object containing information from the incoming POS device that has not already been mapped to other fields in the payment. |
| `statement_descriptor` | Yes | String | A text description suitable for a customer's payment statement. 5-22 characters. |

Sample: Create Payment for the `is_mastercard_pos` Payment Method

- - Request

    - ```curl
      curl -X POST https://sandboxapi.rapyd.net/v1/payments
      -H 'access_key: your-access-key-here' \
      -H 'Content-Type: application/json' \
      -H 'salt: your-random-string-here' \
      -H 'signature: your-calculated-signature-here' \
      -H 'timestamp: your-unix-timestamp-here'
      --data-raw '
      {
          "amount": 1.01,
          "currency": "ILS",
          "payment_method": {
              "type": "il_visa_pos",
              "fields": {
                  "number": "4111111111111111",
                  "expiration_month": "12",
                  "expiration_year": "28",
                  "track2_data": "476170010=28122",
                  "icc_data": "9F2608B27C9C615B88DE61820278009F3602002E9F370473526B11950500800080009C01009F100706011203A400028407A00000000310109F0902008C9F2701809F34034403029F0702FFC09F02060000000001019A032512175F2A0203769F1A0203769F3303E0B8C89F0306000000000000"
              }
          },
          "gateway_id": "251211",
          "merchant_reference_id": "010011",
          "capture": false,
          "expiration": 17665000000,
          "cvv_check": "unchecked",
          "payment_threeds_result": {
              "result_status": "0",
              "verificationValue": "0000000000000000000000000000000000"
          },
          "metadata": {},
          "initiation_type": "card_present",
          "ewallet": "ewallet_b38c61a3622331207e33d6c1cb32fb49",
          "save_payment_method": false,
          "payment_method_options": {
              "payment_device_id": "332019",
              "pos_entry_mode": "EMV_CONTACT"
          }
      }'
      ```
- - Response

    - ```json
      {
          "status": {
              "error_code": "",
              "status": "SUCCESS",
              "message": "",
              "response_code": "",
              "operation_id": "8f874a95-8142-49ee-8d13-d9e652ab91d2"
          },
          "data": {
              "id": "payment_70496244afb4ad1cad16eda7a8007782",
              "amount": 0,
              "original_amount": 1.01,
              "is_partial": false,
              "currency_code": "ILS",
              "country_code": "IL",
              "status": "ACT",
              "description": "",
              "merchant_reference_id": "010011",
              "customer_token": "cus_2ad6c1f734dd05a6f47bad3daf6665a2",
              "payment_method": "card_01afb2b2eefb2455f5c36618be0597b3",
              "payment_method_data": {
                  "id": "card_01afb2b2eefb2455f5c36618be0597b3",
                  "type": "il_visa_pos",
                  "category": "pos",
                  "metadata": null,
                  "image": "",
                  "webhook_url": "",
                  "supporting_documentation": "",
                  "next_action": "not_applicable",
                  "name": null,
                  "last4": "1111",
                  "acs_check": "unchecked",
                  "cvv_check": "unchecked",
                  "bin_details": {
                      "type": "DEBIT",
                      "brand": "VISA",
                      "level": "CLASSIC",
                      "issuer": "CONOTOXIA SP. Z O.O",
                      "country": "PL",
                      "bin_number": "411111"
                  },
                  "expiration_year": "28",
                  "expiration_month": "12",
                  "fingerprint_token": "ocfp_233d187bd4ab11ea95b9121ff706f893",
                  "network_reference_id": "123456"
              },
              "auth_code": null,
              "expiration": 1774001291,
              "captured": false,
              "refunded": false,
              "refunded_amount": 0,
              "receipt_email": "",
              "redirect_url": "",
              "complete_payment_url": "",
              "error_payment_url": "",
              "receipt_number": "",
              "flow_type": "",
              "address": null,
              "statement_descriptor": "Testing XrRNJct",
              "transaction_id": "",
              "created_at": 1771409291,
              "metadata": {},
              "failure_code": "",
              "failure_message": "",
              "paid": false,
              "paid_at": 0,
              "dispute": null,
              "refunds": null,
              "order": null,
              "outcome": null,
              "visual_codes": {},
              "textual_codes": {},
              "instructions": [],
              "ewallet_id": "ewallet_b38c61a3622331207e33d6c1cb32fb49",
              "ewallets": [
                  {
                      "ewallet_id": "ewallet_b38c61a3622331207e33d6c1cb32fb49",
                      "amount": 1.01,
                      "percent": 100,
                      "refunded_amount": 0
                  }
              ],
              "payment_method_options": {
                  "pos_entry_mode": "EMV_CONTACT",
                  "payment_device_id": "332019"
              },
              "payment_method_type": "il_visa_pos",
              "payment_method_type_category": "pos",
              "fx_rate": 1,
              "merchant_requested_currency": null,
              "merchant_requested_amount": null,
              "fixed_side": "",
              "payment_fees": null,
              "invoice": "",
              "escrow": null,
              "group_payment": "",
              "cancel_reason": null,
              "initiation_type": "card_present",
              "mid": "",
              "next_action": "pending_capture",
              "error_code": "",
              "remitter_information": {},
              "save_payment_method": false,
              "merchant_advice_code": null,
              "merchant_advice_message": null,
              "enhanced_data": null,
              "transaction_link_id": null
          }
      }
          
      ```