Creating a Card Payment With 3DS Authentication
Create a card payment that requires 3DS authentication.
Use this procedure when the response to Get Payment Method Required Fields includes the 3d_required field.
For example, a buyer uses a card for a purchase on a website. Because of the amount, you require authentication.
Note
Can you require 3DS authentication for a card payment? It depends on the response to Get Payment Method Required Fields.
'Get Payment Method Required Fields' response
If the
3d_requiredobject does not appear - You cannot request 3DS authentication for the payment method.If the
3d_requiredobject appears - You can request 3DS authentication for the payment method.If
is_requiredis true for the3d_requiredobject - You must include the3d_requiredfield In the 'Create Payment' request.If
is_requiredis false for the3d_requiredobject - You can include the3d_requiredfield In the 'Create Payment' request.
'Create Payment' request
If you set the
3d_requiredfield to true - 3DS authentication will be performed, if it is available for the payment method.If you set the
3d_requiredfield to false - 3DS authentication will not be performed.
Note: The card issuer might require 3DS authentication even when you don't.
Procedure
Create a payment as described in Create Payment, with the following settings:
payment_method- Specify the payment method ID or an object that contains all the required fields for a card.payment_method_options.3d_required- Set to true.{ "payment_method": "card_4facd9b188f2025fdbedb3ab447719ba", "payment_method_options": { "3d_required": true } }
The response shows:
{ "redirect_url": "https://dashboard.rapyd.net/3ds-payment?token=payment_db7f7f5668c25ba4c3eda461a401273d", // . . . }Send the 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
To simulate the buyer's authentication in the sandbox, see Simulating 3DS Authentication - API Method.
Best Practices
Add these parameters to the body of the Create Payment request to significantly improve 3DS conversion rates:
client_details object - Populate all the parameters of this object. It is especially important to include a value for the
ip_addressparameter. See also Create Payment.address object - Add a detailed address object that must include values for the
nameandline_1parameters. See also Create Address.receipt_email parameter - Enter the email address that the receipt for this transaction is sent to. See also Create Payment.
Code Examples
The following is an example for a Create Payment request that includes the above parameters.
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' -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", "country": "CY", "state": "", "city": "Larnaca", "line_1": "123 State Street", "line_2": "APT 34", "phone_number": "+141555555571", "zip": "123456" }, "receipt_email": "johndoe@rapyd.net" } '
Response
{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "f0e4fe4a-76a3-4673-bd57-95695ebf6491" }, "data": { "id": "payment_cba38d710ca02fc2048d014e794527d6", "amount": 0, "original_amount": 99, "is_partial": false, "currency_code": "EUR", "country_code": "CY", "status": "ACT", "description": "", "merchant_reference_id": "", "customer_token": "cus_d78f6c398c0b6dfb1b36f0b86a9a9c13", "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", "network_reference_id": "482602" }, "auth_code": null, "expiration": 1744886838, "captured": true, "refunded": false, "refunded_amount": 0, "receipt_email": "johndoe@rapyd.net", "redirect_url": "https://sandboxcheckout.rapyd.net/3ds-payment?token=payment_cba38d710ca02fc2048d014e794527d6", "complete_payment_url": "https://www.rapyd.net/complete", "error_payment_url": "https://www.rapyd.net/error", "receipt_number": "", "flow_type": "", "address": { "id": "address_da6d7e74b33dee8eaf97757761837729", "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": 1744282038 }, "statement_descriptor": "Doc Team", "transaction_id": "", "created_at": 1744282037, "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 } }
See also the code examples on Create Payment.