Creating a Card-Present Refund

Create a refund for a card-present payment by re-presenting the card at the point of sale (POS).

This operation creates a card-present refund via the Create Refund request.

How

The procedure is made up of the following steps:

Create a card-present payment.
Create a card-present refund.

Create a Card-Present Payment

Create a payment. The request must include the following fields:

payment_method.type - Specify the POS payment method type, for example il_visa_pos.
payment_method.fields - Include the card-present fields captured by the point of sale (POS): number, expiration_month, expiration_year, track2_data, card_sequence_number, and optionally icc_data.
payment_method_options.pos_entry_mode - The entry mode used at the point of sale (POS), for example CONTACTLESS_EMV.
payment_device_id - The point of sale (POS) device ID.

Request

curl -X post 'https://sandboxapi.rapyd.net/v1/payments' \
-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 '
{
    "amount": 85.00,
    "currency": "ILS",
    "payment_device_id": "10000344",
    "merchant_reference_id": "78003001",
    "payment_method_options": {
        "pos_entry_mode": "CONTACTLESS_EMV"
    },
    "payment_method": {
        "type": "il_visa_pos",
        "fields": {
            "number": "4761739001010010",
            "expiration_month": "12",
            "expiration_year": "27",
            "track2_data": "4761739001010010=27122011143816989",
            "card_sequence_number": "001",
            "icc_data": "9F26081FF4B52B36BE5CFF82025C009F2701809F360200059F10120110A00000000000000000000000000000FF"
        }
    }
}

Response

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "a1b2c3d4-0001-1001-2001-300140015001"
    },
    "data": {
        "id": "payment_3fa85f64b5717c9c5c0d8bf0d8c4b2e7",
        "amount": 85,
        "original_amount": 85,
        "is_partial": false,
        "currency_code": "ILS",
        "country_code": "IL",
        "status": "CLO",
        "description": "",
        "merchant_reference_id": "78003001",
        "customer_token": "cus_e4ab0229f97252532993a9d10414cfb1",
        "payment_method": null,
        "payment_method_data": {
            "id": null,
            "type": "il_visa_pos",
            "category": "pos",
            "last4": "0010",
            "expiration_year": "27",
            "expiration_month": "12"
        },
        "auth_code": "012345",
        "expiration": 1749900000,
        "captured": true,
        "refunded": false,
        "refunded_amount": 0,
        "receipt_email": "",
        "redirect_url": "",
        "complete_payment_url": "",
        "error_payment_url": "",
        "receipt_number": "",
        "flow_type": "",
        "address": null,
        "statement_descriptor": "Shva Integration Merch",
        "transaction_id": "",
        "created_at": 1749300000,
        "metadata": {},
        "failure_code": "",
        "failure_message": "",
        "paid": true,
        "paid_at": 1749300000,
        "dispute": null,
        "refunds": null,
        "order": null,
        "outcome": null,
        "visual_codes": {},
        "textual_codes": {},
        "instructions": [],
        "ewallet_id": "ewallet_8818c1e4c2185f4137822ea58f952e2a",
        "ewallets": [
            {
                "ewallet_id": "ewallet_8818c1e4c2185f4137822ea58f952e2a",
                "amount": 85,
                "percent": 100,
                "refunded_amount": 0
            }
        ],
        "payment_method_options": {
            "pos_entry_mode": "CONTACTLESS_EMV"
        },
        "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": "mid_aed21e6c30927c6a3d702ea5a3a19a9d",
        "next_action": "not_applicable",
        "error_code": "",
        "remitter_information": {},
        "save_payment_method": false,
        "merchant_advice_code": null,
        "merchant_advice_message": null,
        "enhanced_data": null,
        "payment_device_id": "10000344",
        "payment_request_id": "payment_req_11223344556677889900aabbccddeeff",
        "transaction_link_id": null
    }
}

The response shows:

In the id field: The payment ID.
initiation_type: card_present.
status: CLO — the payment is complete and eligible for refund.

Create a Card-Present Refund

Note

The payment must reach CLO (closed) status before a refund can be created against it.

Create a card-present refund as described in Create Refund, with the following settings:

Required Fields

payment - The ID of the card-present payment being refunded.
amount - Refund amount.
currency - Currency of the refund. ISO 4217 three-letter code.
payment_device_id - The point of sale (POS) device ID. Alphanumeric, maximum 8 characters.
payment_method_options.pos_entry_mode - The entry mode used at the point of sale (POS) during the refund. Accepted values: : CONTACTLESS_EMV, CHIP, SWIPE, MAGNETIC_STRIPE, FALLBACK.
payment_method.type - The payment method type, for example il_visa_pos.
payment_method.fields.number - Full card PAN.
payment_method.fields.expiration_month - Card expiry month,
payment_method.fields.expiration_year - Card expiry year.
payment_method.fields.track2_data - EMV tag 57. Must contain the = separator. A malformed but non-empty value is accepted with a warning and not forwarded. An absent or empty value returns a validation error.
payment_method.fields.card_sequence_number - EMV tag 5F34. Three digits, left-padded with 0, for example 001..

Optional Fields

payment_method.fields.icc_data - ICC/EMV chip data in Tag-Length-Value (TLV) format, maximum 510 characters. Omitted for magnetic-stripe fallback or non-chip cards.
merchant_reference_id - Merchant's own reference ID.
statement_descriptor - Text shown on the cardholder statement.
metadata - Arbitrary key-value pairs passed through to the refund record.