Skip to content

Rapyd

Process card payments through Rapyd: the contract, the supported features and the test cards.

For PayFacs and ISOs that process through Rapyd. Ginger sends card payments to the Rapyd payment gateway with the Rapyd API keys of the project, and Rapyd authenticates the customer with 3-D Secure (3DS). You configure the keys and the Rapyd wallet that receives the funds per project, in a contract.

How it works

Rapyd is the card processor of your platform, or of the merchants you assign to it (see Payments). A card payment through Rapyd goes like this:

  1. The customer enters the card details on the hosted payment page, or in the merchant's own checkout. Ginger stores the card in its vault.
  2. Ginger creates the payment at Rapyd. The Rapyd payment method is derived from the country of the merchant's billing address and the card brand, such as nl_visa_card.
  3. Rapyd returns a 3DS page. The customer completes 3DS there and returns to Ginger.
  4. Rapyd reports the result. The transaction becomes successful, or gets the status error with a reason from Rapyd.

Ginger asks Rapyd for 3DS on every customer-initiated payment, except when a dynamic 3DS rule of the project prefers to skip it. Recurring payments, Apple Pay and Google Pay with a cryptogram don't need 3DS.

Rapyd uses the customer's name and billing address of the order to authenticate the cardholder, and needs a cardholder name. Ask your merchants to send complete customer details: see Send complete customer details.

Contract

Rapyd gives you the API keys of the merchant's Rapyd account and the ID of its wallet. Fill them in on the Rapyd contract of the project: in the Admin portal, open the project, go to the Payment Method Contracts tab, switch on Rapyd and open it. With the Boarding API, set the rapyd contract of the project.

Live payments need the access_key and secret_key. Set the ewallet_id for the wallet that receives the collected funds, and a settlement_currency to let Rapyd convert payments in other currencies. The contract also holds the brands and currencies of the project, the capture modes and the dynamic 3-D Secure rules. See the rapyd fields of Update a project contract in the API reference.

The merchant also needs a billing address with a country: Ginger can't start a Rapyd payment without it.

curl https://api.example.com/v1/admin/merchants/$MERCHANT_ID/projects/$PROJECT_ID/contracts/rapyd/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --request PUT \
  --data '{
    "access_key": "<Rapyd access key>",
    "secret_key": "<Rapyd secret key>",
    "ewallet_id": "<Rapyd wallet ID>",
    "currencies": ["EUR", "USD"]
  }'

The project also needs permission for /payment-methods/credit-card/ with POST: see Permissions.

Keep the keys secret

The secret key gives access to the merchant's Rapyd account. Only enter it in the contract.

Payment methods and features

Rapyd
Payment methodscredit-card, apple-pay, google-pay
Card brandsVisa, Mastercard, Maestro, American Express
3-D SecureThrough Rapyd, with dynamic 3DS rules
Sale and refundYes
Pre-authorisationYes, when enabled in the contract, for at most 7 days
CaptureOne capture per pre-authorisation
VoidThe full amount, before a capture
One-click paymentsYes, also with a zero amount for the first payment
Recurring paymentsYes, scheduled and unscheduled
Currency conversionWith settlement_currency

For the requests, see Pre-authorizations, Refunds, One-click payments and Recurring payments in the payment acceptance docs. The changelog lists when each feature arrived.

Test cards

Test with a project in test mode (status active-testing). Test payments go to the Rapyd sandbox. When the contract of a test project has no keys, Ginger uses the sandbox keys of your platform.

BrandCard numberCVCResult
Visa4111111111111111Any 3 digitsSuccess
Visa4462030000000000Any 3 digitsSuccess
Mastercard5544330000000037Any 3 digitsSuccess
American Express371881634498004Any 4 digitsSuccess
Visa4111111111111105Any 3 digitsDeclined: do not honor
Visa4111111111111143Any 3 digitsDeclined: stolen card, pick up
Visa4111111111111151Any 3 digitsDeclined: insufficient funds

Rapyd lists more in its card numbers for testing.

Next steps