Creating a Card Payment With 3DS Authentication - Rapyd 3DS
This procedure describes how to create a card payment that uses Rapyd's 3DS authentication. The card issuer might require 3DS even when it is not specified in the payment request. This procedure is relevant to the production environment.
Related Information
External 3DS provider - Creating a payment that uses an external 3DS provider. API production environment. See Creating a Card Payment With 3DS Authentication - External 3DS.
Simulation - Simulating a payment with Rapyd's 3DS authentication. API sandbox environment. See Simulating 'Create Payment' with 3DS - API.
Prerequisites
A payment method that supports 3DS authentication. If the response to Get Payment Method Required Fields includes
payment_method_options.3d_required, 3DS is supported.Keys to the production environment for your user.
How
Create a payment as described in Create Payment, with the following settings:
payment_method- Specify one of the following:The ID of the customer's payment method.
A 'payment method' object that contains all required fields.
payment_method_options.3d_required- Set to true.To improve your authentication success rate, Rapyd strongly recommends the following fields:
Specify an
addressobject that describes the billing address for the card. Relevant for Visa payments:name- Name of the cardholder. Required.line_1- Street address, including street and building number. Required.city- City.state- Major political subdivision of the country.country- Country. 2-letter ISO 3166-1 ALPHA-2 code.zip- Postal code.phone_number- Phone number associated with this specific address in E.164 format.
Specify a
client_detailsobject. Populate all fields, especiallyip_address.accept_header- Set to text/html.ip_address- IP address of the cardholder's browser. Relevant for Visa and Mastercard payments.java_enabled- Indicates whether the cardholder's browser supports Java.java_script_enabled- Indicates whether the cardholder's browser supports JavaScript.screen_color_depth- Indicates the number of bits used to define colors in the cardholder's browser. Valid values: 1, 4, 8, 15, 16, 24, 32, 48.screen_height- Height of the browser's screen in pixels. Relevant for Visa payments.screen_width- Width of the browser's screen in pixels. Relevant for Visa payments.time_zone_offset- Number of minutes away from GMT. Positive or negative integer.
receipt_email- Enter the email address that the receipt for this transaction is sent to.
Request
curl -X post https://api.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' -d '{ "amount": "99", "currency": "EUR", "complete_payment_url": "https://www.rapyd.net/complete", "error_payment_url": "https://www.rapyd.net/error", "payment_method_options": { "3d_required": true }, "payment_method": { "type": "cy_visa_card", "fields": { "name": "John Doe", "number": "4111111111111111", "expiration_month": "04", "expiration_year": "28", "cvv": "123" } }, "client_details": { "time_zone_offset": 300, "language": "en-US", "java_enabled": true, "java_script_enabled": true, "screen_color_depth": 16, "screen_height": 768, "screen_width": 1024, "accept_header": "text/html", "ip_address": "162.162.162.162" }, "address": { "name": "John Doe", "line_1": "123 State Street", "line_2": "Apt. 34", "city": "Larnaca", "state": "", "country": "CY", "zip": "123456", "phone_number": "+14155555571" }, "receipt_email": "johndoe@rapyd.net" }'
Response
{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "62ef7b86-e43c-47b3-86d7-3e5b7511a4f2" }, "data": { "id": "payment_a9ee4a360faead99239df7b8b3602416", "amount": 0, "original_amount": 99, "is_partial": false, "currency_code": "EUR", "country_code": "CY", "status": "ACT", "description": "", "merchant_reference_id": "", "customer_token": "cus_4935a18ff0e1beaa3d5d794f8d1c7751", "payment_method": null, "payment_method_data": { "id": null, "type": "cy_visa_card", "category": "card", "metadata": null, "image": "", "webhook_url": "", "supporting_documentation": "", "next_action": "3d_verification", "name": "John Doe", "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": "04", "fingerprint_token": "ocfp_e599f990674473ce6283b245e9ad2467", "payment_account_reference": "V001FIBDU4IRFGR2A8Z3I9WHCXXBC", "network_reference_id": "631840" }, "auth_code": null, "expiration": 1751295161, "captured": true, "refunded": false, "refunded_amount": 0, "receipt_email": "johndoe@rapyd.net", "redirect_url": "https://sandboxcheckout.rapyd.net/3ds-payment?token=payment_a9ee4a360faead99239df7b8b3602416", "complete_payment_url": "https://www.rapyd.net/complete", "error_payment_url": "https://www.rapyd.net/error", "receipt_number": "", "flow_type": "", "address": { "id": "address_dec4b5a3d584a7636206e8ceef1a6a96", "name": "John Doe", "line_1": "123 State Street", "line_2": "Apt. 34", "line_3": "", "city": "Larnaca", "state": "", "country": "CY", "zip": "123456", "phone_number": "+14155555571", "metadata": {}, "canton": "", "district": "", "created_at": 1750690362 }, "statement_descriptor": "Doc Team", "transaction_id": "", "created_at": 1750690361, "metadata": {}, "failure_code": "", "failure_message": "", "paid": false, "paid_at": 0, "dispute": null, "refunds": null, "order": null, "outcome": null, "visual_codes": {}, "textual_codes": {}, "instructions": [ { "name": "instructions", "steps": [ { "step1": "" } ] } ], "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861", "ewallets": [ { "ewallet_id": "ewallet_c1943cfeda5f98247ab117e5d2648861", "amount": 99, "percent": 100, "refunded_amount": 0 } ], "payment_method_options": { "3d_required": true }, "payment_method_type": "cy_visa_card", "payment_method_type_category": "card", "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": "customer_present", "mid": "", "next_action": "3d_verification", "error_code": "", "remitter_information": {}, "save_payment_method": false, "merchant_advice_code": null, "merchant_advice_message": null, "authentication_result": { "eci": null, "result": "R", "version": "2.2.0", "cardholder_info": null }, "transaction_link_id": null } }
Send the redirect URL to the buyer.
The buyer opens the URL. An authentication page opens and the buyer receives an authentication code.
The buyer enters the code on the authentication page. Rapyd completes the payment.
Note
Transactions with 3DS authentication must be authenticated within 15 minutes.