Integration of Card-Present Transactions

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. See also Upload File to Communication Center.
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.

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

GET{base_url}/payment_methods/required_fields/is_visa_pos

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 -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

{
    "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’ 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.