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.
api_version - see Versioning for API Methods.
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.
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. For webhooks, see Webhook Authentication.
timestamp - The time of the request, in 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.
base_url: The URL of the server. For example, `https://api.rapyd.net/v1`	Rapyd’s production environment.

URL

Description

base_url: The URL of the server.

For example, https://sandboxapi.rapyd.net/v1

Rapyd’s sandbox environment.

base_url: The URL of the server.

For example, https://api.rapyd.net/v1

Rapyd’s production environment.

Nota

The merchant must also be subscribed to receive related webhooks to their defined server address.

Step 1: Pair Payment Device

Pair the payment device with a Rapyd wallet. This step is required since funds from transactions made on the device do not reach the merchant unless the device is paired. The device_id returned in the response is the value to pass as payment_device_id in the 'Create Payment' request in Step 2. See also Pair Payment Device.

Endpoint:POST{base_url}/payment_device/pair

Body Parameters:

Body Parameter	Required	Type	Description
`currency`	Yes	string	Currency of the device. Three-letter ISO 4217 code.
`merchant_ewallet`	Yes	string	ID of the merchant wallet that is associated with the physical address where the device is installed. String starting with ewallet_.
`settlement_ewallet`	Yes	string	ID of the wallet that receives the funds from transactions on the device. String starting with ewallet_.

Response Parameters: The following fields in the data object:

Response Parameter	Type	Description
`device_id`	string	ID of the device. Pass this value as `payment_device_id` in the Create Payment request. It must also be encoded on the device, following the manufacturer's instructions.
`merchant_id`	string	ID of the merchant.

Sample: Pair Payment Device

Request

curl -X POST https://sandboxapi.rapyd.net/v1/payment_device/pair \
-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 '
{
    "merchant_ewallet": "ewallet_f992d07ec267b39c4048f187d896d98b",
    "settlement_ewallet": "ewallet_f992d07ec267b39c4048f187d896d98b",
    "currency": "ISK"
}'

Response

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "e7dcbb93-1aa2-45ce-8c1c-6e5556929953"
    },
    "data": {
        "device_id": "185064",
        "merchant_id": "08H7fg65"
    }
}
    

Step 2: Create Payment

Create a payment using the is_visa_pos, is_mastercard_pos or is_amex_pos payment method. Set payment_device_id to the device_id returned by the Pair Payment Device call in Step 1.

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.
`capture`	No	boolean	Determines when the payment is processed for capture. `true` - the payment is authorized and captured in one step. `false` - the payment is only authorized and must be captured later.
`currency`	Yes	string	Defines the currency of the transaction. Three-letter ISO 4217 code.
`ewallet`	Yes	string	ID of the wallet that the money is paid into. String starting with ewallet_.
`initiation_type`	Yes	string	Indicates how the transaction was initiated. One of the following values: card_present customer_present installment moto recurring unscheduled
`merchant_reference_id`	Yes	string	Your unique identifier for the transaction, such as an order ID or a UUID.
`payment_method`	Yes	object	Contains the `type` of the payment method and its `fields`. See the table below.
`payment_method_options`	No	object	Contains additional POS options for the payment. See the table below.
`payment_advice`	No	object	A JSON object containing information from the incoming POS device that has not already been mapped to other fields in the payment.
`payment_device_id`	No	string	The `device_id` returned in the response of the Pair Payment Device call (Step 1). It is a unique ID that applies to the payment 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.
`statement_descriptor`	No	string	A text description suitable for a customer's payment statement. 5-22 characters.

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), and Tag 5A (Application Primary Account Number). Tag 5F34 (PAN Sequence Number) must be included when it is available on the card. 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` Parameter	Required	Type	Description
`pos_entry_mode`	No	String	Indicates how the card data was entered at the POS terminal. Supported values include `CONTACTLESS_EMV` (contactless EMV) and `EMV_CONTACT` (contact EMV chip).

Sample: Create Payment (Sale) for the is_visa_pos Payment Method