Rapyd Gateway Guide
Services and Compatibility
- Payment Gateway Company Name:
- Rapyd
- Services that work with Spreedly:
-
- Rapyd
- Supported operations:
- Purchase, Authorize, Capture, Refund, Void, Verify, Store
- Supported payment types:
- Credit Card, Bank Account
- Spreedly 3DS2 Global Supported
- Yes
- Gateway Specific 3DS2 Supported
- Yes
- Populate MIT GSF Support
- No
- Regions:
- Africa, Asia Pacific, Europe, Latin America, Middle East, North America
- API endpoint URL:
-
https://api.rapyd.net/v1/
Authentication and Security
- Specific names for credentials:
- Access Key, Secret Key
Onboarding Merchants in:
-
Canada
-
Chile
-
Colombia
-
Dominican Republic
-
El Salvador
-
Peru
-
Portugal
-
Virgin Islands (U.S.)
-
Australia
-
Hong Kong
-
India
-
Indonesia
-
Japan
-
Malaysia
-
New Zealand
-
Philippines
-
Singapore
-
Korea (Republic of)
-
Taiwan
-
Thailand
-
Vietnam
-
Andorra
-
Austria
-
Belgium
-
Bosnia and Herzegovina
-
Bulgaria
-
Croatia
-
Cyprus
-
Czechia
-
Denmark
-
Estonia
-
Finland
-
France
-
Georgia
-
Germany
-
Gibraltar
-
Greece
-
Greenland
-
Hungary
-
Iceland
-
Ireland
-
Israel
-
Italy
-
Latvia
-
Liechtenstein
-
Lithuania
-
Luxembourg
-
Macedonia (the former Yugoslav Republic of)
-
Malta
-
Moldova (Republic of)
-
Monaco
-
Montenegro
-
Netherlands
-
United Kingdom
-
Norway
-
Poland
-
Romania
-
Russian Federation
-
San Marino
-
Slovakia
-
Slovenia
-
South Africa
-
Spain
-
Sweden
-
Switzerland
-
Turkey
-
Holy See
To add a Rapyd gateway:
Adding a Rapyd gateway
curl https://core.spreedly.com/v1/gateways.xml \
-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/xml' \
-d '<gateway>
<gateway_type>rapyd</gateway_type>
<access_key>Your access key</access_key>
<secret_key>Your secret key</secret_key>
</gateway>'
<gateway>
<token>5VvMj7lMsBBnvdMlypEYJ5qRQ8L</token>
<gateway_type>rapyd</gateway_type>
<name>Rapyd</name>
<description nil="true"/>
<merchant_profile_key nil="true"/>
<sub_merchant_key nil="true"/>
<characteristics>
<supports_purchase type="boolean">true</supports_purchase>
<supports_authorize type="boolean">true</supports_authorize>
<supports_capture type="boolean">true</supports_capture>
<supports_credit type="boolean">true</supports_credit>
<supports_general_credit type="boolean">false</supports_general_credit>
<supports_void type="boolean">true</supports_void>
<supports_adjust type="boolean">false</supports_adjust>
<supports_verify type="boolean">true</supports_verify>
<supports_reference_purchase type="boolean">false</supports_reference_purchase>
<supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
<supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
<supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
<supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
<supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
<supports_3dsecure_2_mpi_purchase type="boolean">false</supports_3dsecure_2_mpi_purchase>
<supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_authorize>
<supports_store type="boolean">false</supports_store>
<supports_remove type="boolean">false</supports_remove>
<supports_fraud_review type="boolean">false</supports_fraud_review>
<supports_network_tokenization type="boolean">false</supports_network_tokenization>
<supports_populate_mit_fields type="boolean">false</supports_populate_mit_fields>
</characteristics>
<credentials>
</credentials>
<gateway_settings>
</gateway_settings>
<gateway_specific_fields>
<gateway_specific_field>payment_purpose</gateway_specific_field>
<gateway_specific_field>proof_of_authorization</gateway_specific_field>
<gateway_specific_field>pm_type</gateway_specific_field>
<gateway_specific_field>ewallet_id</gateway_specific_field>
<gateway_specific_field>metadata</gateway_specific_field>
</gateway_specific_fields>
<payment_methods>
<payment_method>credit_card</payment_method>
<payment_method>bank_account</payment_method>
</payment_methods>
<state>retained</state>
<redacted type="boolean">false</redacted>
<sandbox type="boolean">false</sandbox>
<mode>default</mode>
<created_at type="dateTime">2022-04-15T19:09:17Z</created_at>
<updated_at type="dateTime">2022-04-15T19:09:17Z</updated_at>
</gateway>
env = Spreedly::Environment.new('C7cRfNJGODKh4Iu5Ox3PToKjniY', '4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ', base_url: 'https://core.spreedly.com')
env.add_gateway(:rapyd, access_key: "Your access key", secret_key: "Your secret key")
#<Spreedly::Gateway:0x00007f81590c6b38
@token="35TUJ8o4fZruPbHOxsPKCYtv7Vx",
@created_at="2022-04-15T19:09:17Z",
@updated_at="2022-04-15T19:09:17Z",
@gateway_type="rapyd",
@state="retained",
@name="Rapyd",
@credentials={}>
Third-party 3D Secure 2 Auth Data
Spreedly will automatically handle the field mapping for sending third-party 3DS2 authentication data to Rapyd. For more information about how to use this feature, see the 3DS2 Third-party Authentication Guide. Spreedly fields map to the relevant Rapyd fields as described in the following table. Please see Rapyd’s third-party 3DS2 documentation for more information.
Spreedly Field | Rapyd Field |
---|---|
three_ds_version |
3d_version |
ecommerce_indicator |
eci |
authentication_value |
cavv |
directory_server_transaction_id |
ds_trans_id |
xid |
xid |
Considerations for Gateway Specific 3DS
Rapyd supports 3DS Gateway Specific by sending an attempt_3dsecure
parameter with a value of true
, as the 3DS Gateway Specific field guide shows.
It is important to mention that Rapyd implementation for their 3DS flow is an asynchronous one, which means that after the user finishes the 3DS challenge the redirection that happens at that moment doesn’t carry with it the 3DS results, instead, the ACS server notifies Rapyd and then Rapyd sends events to the webhook url configured on their dashboard.
That means that Rapyd is going to redirect the user to the redirect_url
specified on the purchase-authorize request and then when it gets the 3DS challenge results, is going to send a (PAYMENT_COMPLETE
| PAYMENT_UPDATED
| PAYMENT_FAILURE
) notification to the webhook url (which should be Spreedly webhook url), then Spreedly is going to process the event and notify the merchant at the callback_url
specified on the request.
What does all this mean for merchant implementation?
Rapyd flow is different than other gateways so the merchant needs to:
- Manually setup the webhook url on Rapyd dashboard to
https://core.spreedly.com/rapyd/webhooks
. - Take into consideration that
redirect_url
page should be something like “your payment is pending confirmation” page. - Implement logic to receive the notifications from Spreedly at the
callback_url
and update the user accordingly. - There is no need to implement any complete request as with other gateways just wait for the notification.
Custom request params related with 3DS Gateway Specific:
Additionally, the merchant can include the following parameters as part of the Gateway Specific Fields (GSF):
complete_payment_url
: This is the URL where you want the 3DS site to redirect the customer if the payment succeeds. (overrides the defaultredirect_url
)error_payment_url
: This is the URL where you want the 3DS site to redirect the customer if the payment fails.
Full Name and Address on Purchase and Authorize
Rapyd requires the full name and address of the payee on some payment methods. Spreedly recommends customers refer to Rapyd’s documentation to verify ahead of time that payment methods vaulted with Spreedly contain the necessary information.
Payment Method Type
The pm_type
field is required for purchase
and authorize
transactions. This value correlates to the Rapyd Payment
Method Type value and is composed of a country code, card brand, and the card type (i.e., us_visa_card
). Additional Payment Method Type configurations
need to be setup with Rapyd and can be done through their support. Rapyd accounts are configured for specific payment method types. They list
available types by country via an API. Rapyd’s documentation provides more information.
Bank Account Transactions
Bank Account verification is required prior to transacting with Bank Account. Please see the Rapyd documentation for more information.
The Gateway Specific Fields proof_of_authorization
and payment_purpose
are required when using a bank account. For more information, see Rapyd’s Payment Method Required Fields.
Authorize
cannot be used for ACH payments. Please use Purchase
. As soon as Rapyd receives a successful request they will mark it as pending (ACT). After processing at Rapyd, transactions will be marked complete (CLO) which is usually within 48 hours but in some cases can take longer. The CLO status will be notified via webhook (not via Spreedly) and reflected on the Rapyd client portal.
Stored Credentials
For Rapyd, sending stored credential fields can be done using Spreedly’s first class support. Sending stored credential data is simple. For any Authorize
or Purchase
request, you need to include two fields which tell Spreedly a little bit more about the nature of the transaction:
stored_credential_initiator
stored_credential_reason_type
Rapyd needs to enable this feature for your account. Please reach out to them and ask to enable the use of network_reference_id on the Payment Method Data object. You should provide that you are using Spreedly for your PCI compliance. Without enabling this feature, Rapyd will require CVV on every transaction.
Learn more about how Spreedly enables seamless use of stored credentials by reviewing our Stored Credentials Guide.
Card on file and recurring transactions that use network reference id is not supported outside of the EU. Rapyd will require CVV to process all transactions in the rest of the world.
Gateway Specific Fields
Spreedly supports the following gateway specific fields when transacting with Rapyd:
proof_of_authorization
payment_purpose
pm_type
ewallet_id
metadata
complete_payment_url
error_payment_url
description
statement_descriptor
three_d_required
customer_id
network_transaction_id
initiation_type
merchant_reference_id
recurrence_type
customer_id
accepts a string that is Rapyd’s customer id to link customer transactions with.
The majority of GSFs for Rapyd are Payment Method Required Fields. Please refer to their documentation for proper usage.
Metadata
The metadata
field contains custom data defined by the client, in the format of a JSON object. Merchants may use this
field to store additional information associated with the transaction. Rapyd does not use the metadata for any purpose.
Please refer to using a payment method for more information on how to send GSFs
Gateway specific response fields
Responses from Rapyd gateway may contain the following fields:
* redirect_url
* next_action
* merchant_reference_id
* network_reference_id
* customer_token
* payment_method
fields.
You can find these in the gateway_specific_response_fields
.
For example, an authorize
transaction could have something like this:
<transaction>
<token>LgpTNGjsWQs9DwdxcbreUVz0R8p</token>
<transaction_type>Authorization</transaction_type>
<gateway_specific_response_fields>
<rapyd>
<redirect_url>00</redirect_url>
<next_action>100</next_action>
<merchant_reference_id>1234a_1234b_1234c</merchant_reference_id>
<network_reference_id>123456</network_reference_id>
<customer_token>789</customer_token>
<payment_method>123abc</payment_method>
</rapyd>
</gateway_specific_response_fields>
</transaction>