Rapyd Gateway Guide

Rapyd fact sheet

Adding a Rapyd gateway

To add 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_offsite_synchronous_purchase type="boolean">false</supports_offsite_synchronous_purchase>
    <supports_offsite_synchronous_authorize type="boolean">false</supports_offsite_synchronous_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">true</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">true</supports_store>
    <supports_remove type="boolean">true</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>
    <supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
    <supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
    <supports_transaction_retry type="boolean">false</supports_transaction_retry>
    <supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
    <supports_3dsecure_2_purchase type="boolean">true</supports_3dsecure_2_purchase>
    <supports_3dsecure_2_authorize type="boolean">true</supports_3dsecure_2_authorize>
    <supports_stored_credentials type="boolean">true</supports_stored_credentials>
  </characteristics>
  <credentials>
  </credentials>
  <gateway_settings>
    <url_override nil="true"/>
  </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_field>complete_payment_url</gateway_specific_field>
    <gateway_specific_field>error_payment_url</gateway_specific_field>
    <gateway_specific_field>description</gateway_specific_field>
    <gateway_specific_field>statement_descriptor</gateway_specific_field>
    <gateway_specific_field>customer_id</gateway_specific_field>
    <gateway_specific_field>network_transaction_id</gateway_specific_field>
    <gateway_specific_field>initiation_type</gateway_specific_field>
    <gateway_specific_field>merchant_reference_id</gateway_specific_field>
    <gateway_specific_field>recurrence_type</gateway_specific_field>
    <gateway_specific_field>force_3d_secure</gateway_specific_field>
    <gateway_specific_field>idempotency_key</gateway_specific_field>
    <gateway_specific_field>save_payment_method</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>bank_account</payment_method>
    <payment_method>third_party_token</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>

When a customer creates a Rapyd gateway like above they will interact with the endpoint https://api.rapyd.net/v1/. If you intend to create payments using the “payment-redirect” Rapyd API endpoint, it is necessary to include the url_override parameter with the value "payment_redirect" when creating the Rapyd gateway. In this case, you will connect to one of the following endpoints based on whether you are operating in the sandbox environment or the production environment:

Sandbox endpoint: https://sandboxpayment-redirect.rapyd.net/v1
Production endpoint: https://payment-redirect.rapyd.net/v1

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 Application ID</access_key>
        <secret_key>Your Certificate ID</secret_key>
        <url_override>payment_redirect</url_override>
      </gateway>'

Third-party 3DS2 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 this all 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 to 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 default redirect_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.

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
customer_id
network_transaction_id
initiation_type
merchant_reference_id
recurrence_type
force_3d_secure
idempotency_key
save_payment_method

customer_id accepts a string that is Rapyd’s customer id to link customer transactions with.

The idempotency_key is a GSF added as a key-value header to the request. It is used to prevent duplicate transactions.

When a transaction is initiated with the same idempotency key and the same amount in the next 24 hours, Rapyd will respond by returning the details of the original transaction, treating it as an idempotent request. However, if a transaction is attempted with the same idempotency key but a different amount, Rapyd will process it as a new transaction, and it won't be considered idempotent.

By default, Rapyd enables the idempotency check for Create Payment requests only. If you want idempotency checks on all POST and PUT requests, you can enable it by contacting Rapyd support.

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.

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
operation_id

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>
      <operation_id>5678a_5678b_5678c</operation_id>
    </rapyd>
  </gateway_specific_response_fields>
</transaction>

To request any gateway_specific_fields or gateway_specific_response_fields, please contact Support with your request and the gateway documentation for the fields of interest.