---
title: "Pair Payment Device"
source_url: https://docs.rapyd.net/en/pair-payment-device.html
lang: en
---

# Pair Payment Device

Pair a payment device with a Rapyd wallet. This operation assigns a unique ID to the device and connects it to the merchant's wallet.

This API endpoint establishes a connection between a payment device and the Rapyd system, enabling seamless communication. It returns the necessary credentials that are used to configure the device, ensuring that funds are accurately routed to the associated merchant account during a transaction. This step is mandatory, as without it, funds will not be sent to the merchant for transactions carried out with the payment device. When you receive the device credentials (`device_id` and `merchant_id`), you can use them in the hardware manufacturer's management system (for example, MAX Store) to configure the payment device during the deployment of the Rapyd Core app. Alternatively, if you develop your own payment application (not relying on the Rapyd Core app), make sure to include these IDs in your transaction requests to ensure proper integration.

> **Note:**
>
> The merchant must encode the value of the `device_id` response parameter on the device using the manufacturer's instructions.

> **Note:**
>
> The code samples include successful requests (200), bad requests (400), and an unauthorized request (401).
>
> For a list of all error messages that appear due to bad requests, see:
>
> - [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors")

### Parameters

### Request Header Parameters

- - access_key
  - Unique access key provided by Rapyd for each authorized user.

    See [Developers](https://docs.rapyd.net/en/developers.md "Developers").
- - Content-Type
  - Indicates that the data appears in JSON format. Set to **application/json**.
- - idempotency
  - A unique key that prevents the platform from creating the same object twice.

    See [Idempotency](https://docs.rapyd.net/en/idempotency.md "Idempotency").
- - salt
  - Random string. Recommended length: 8-16 characters.
- - signature
  - Signature calculated for each request individually.

    See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures").
- - timestamp
  - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds).

### Request Body Parameters

- - currency
  - Currency of the device. Three-letter ISO 4217 code.
- - merchant_ewallet
  - ID of the merchant wallet that is associated with the physical address where the device is installed. String starting with **ewallet_**.
- - settlement_ewallet
  - ID of the wallet that receives the funds from transactions on the device. String starting with **ewallet_**.

### Response Parameters

- - device_id
  - ID of the device.
- - merchant_id
  - ID of the merchant.

- /v1/payment_device/pair

- Pair Payment Device
- ```curl
  curl -X post
  'https://sandboxapi.rapyd.net/v1/payment_device/pair' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
    "merchant_ewallet": "ewallet_b97730030da9cb3d567977672331fa88",
    "settlement_ewallet": "ewallet_42dbfb7fd7638a95d6ba084ac07dec1e",
    "currency": "EUR"
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "",
          "status": "SUCCESS",
          "message": "",
          "response_code": "",
          "operation_id": "d7f0efba-d22a-4974-af94-76027d7ea0ab"
      },
      "data": {
  		"device_id": "00001473",
  		"merchant_id": "08H7fg65"
      }
  }
  ```

- Bad Request - Invalid Currency
- ```curl
  curl -X post
  'https://sandboxapi.rapyd.net/v1/payment_device/pair' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
    "merchant_ewallet": "ewallet_b97730030da9cb3d567977672331fa88",
    "settlement_ewallet": "ewallet_42dbfb7fd7638a95d6ba084ac07dec1e",
    "currency": "USD"
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "ERROR_UNSUPPORTED_CURRENCY",
          "status": "ERROR",
          "message": "The request attempted an operation that requires a currency, but the value is not supported. The request was rejected. Corrective action: Use a supported currency.",
          "response_code": "ERROR_UNSUPPORTED_CURRENCY",
          "operation_id": "5a4e274d-e5b3-4ba7-9156-98d6ef024681"
      }
  }
  ```

- Bad Request - Missing Required Field
- ```curl
  curl -X post
  'https://sandboxapi.rapyd.net/v1/payment_device/pair' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
    "merchant_ewallet": "ewallet_b97730030da9cb3d567977672331fa88",
    "settlement_ewallet": "",
    "currency": "EUR"
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "INVALID_FIELDS - [settlement_ewallet]",
          "status": "ERROR",
          "message": "The request attempted an operation, but one or more of the fields did not have a valid value. The request was rejected. Corrective action: Use valid values. The names of the affected fields appear at the end of the error code. See the API Reference for details.",
          "response_code": "INVALID_FIELDS - [settlement_ewallet]",
          "operation_id": "5c103b2c-d7d8-4506-ad92-40a2f513380a"
      }
  }
  ```

- Unauthorized
- ```curl
  curl -X post
  'https://sandboxapi.rapyd.net/v1/payment_device/pair' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
    "merchant_ewallet": "ewallet_b97730030da9cb3d567977672331fa88",
    "settlement_ewallet": "ewallet_42dbfb7fd7638a95d6ba084ac07dec1e",
    "currency": "EUR"
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "UNAUTHENTICATED_API_CALL",
          "status": "ERROR",
          "message": "The request was rejected due to an authentication issue. Corrective action: Check the status of your account in the 'Account Details' page of the Client Portal.",
          "response_code": "UNAUTHENTICATED_API_CALL",
          "operation_id": "95c8c6bf-418a-446b-932c-e0979517708e"
      }
  }
  ```