External Network Tokenization
Securely accept card payments using network tokens provisioned by third-party on-behalf token requestors.
You can use Rapyd to accept card payments with a third party network token. Tokens are alphanumeric strings that can be used instead of a PAN (Primary Account Number) for card transactions. Network tokens are a specific kind of card token issued by a card network like Visa or Mastercard.
A third-party on-behalf token requestor can ask Visa or Mastercard to issue a network token. A token requestor has an integration with Visa and Mastercard Token Services. The network tokens are used by the merchants working with the token requestor.
Network tokens are used to make card transactions more secure. The PAN (Primary Account Number) of a credit card is a 16-19 digit number used to identify the card. The network token acts as a placeholder to protect sensitive information during transactions. A network token is tied to a specific card, merchant, and token provider, which provides increased safety. For example, two different network tokens will be issued for a card that is tokenized by two different merchants.
There are two elements to network tokens: the token string and the tavv (token authentication verification value). The tavv is a cryptogram generated by the card network and acts as an additional security measure. The merchant obtains new tavv cryptograms from the token provider (third-party token requestor).
You can use the Rapyd Collect API to initiate a card payment using a third-party network token. Network tokenization provides a more secure way to process your card payments, and helps to prevent fraud.
You are a partner or integrator working with multiple acquirers. You're looking for card acquiring services through Rapyd. You contract with a third-party on-behalf token requestor. You register your merchants with the token provider.
You send your tokenization requests to the third-party token provider for the card information you have on file. You receive a network token in return, and store the network token for the card payment. During payment, you request a tavv cryptogram from the token requestor. You can then send your card payment to any acquirer.
The customer completes the card payment in checkout on your website and consents to save their card information.
The card information is sent to the third-party token provider, who requests a token for the card from the appropriate card network.
You request Rapyd to process the card payment with a network token and token cryptogram.
Rapyd processes the payment and sends the response and webhook back to you.
You display your purchase success page to the customer.
PCI Certification
Only clients with PCI-DSS certification can handle personal identifying information for cards. This method is available to merchants who have signed a special agreement with Rapyd.
Decide the Card Payment Types You'll Accept in a Chosen Country. Use List Payment Methods by Country with the following parameters:
IS and ISK are used for country and currency in the sample codes below. is_visa_card is the payment method type.
Description of Query Parameters
Query Parameter | Description |
|---|---|
country | Enter IS as the country code. |
currency | Enter ISK as the currency code. |
List Payment Methods by Country Request
Request
// Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/country?country=IS¤cy=ISK // Message body absent
List Payment Methods by Country Response
Response
{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "c53a2e6b-74f6-42ba-a0a3-21724346a36c" }, "data": [ { "type": "is_iban", "name": "tEST---is_iban", "category": "bank_transfer", "image": "https://iconslib.rapyd.net/checkout/is_iban.png", "country": "IS", "payment_flow_type": "card", "currencies": [ "ISK" ], "status": 1, "is_cancelable": false, "payment_options": [ { "name": "capture", "type": "boolean", "regex": "", "description": "Determines when the payment is processed for capture", "is_required": false, "is_updatable": false }, { "name": "complete_payment_url", "type": "string", "regex": "", "description": "URL where the customer is redirected for final steps in completing the operation.", "is_required": true, "is_updatable": false }, { "name": "error_payment_url", "type": "string", "regex": "", "description": "URL where the customer is redirected in case of an error in the operation.", "is_required": true, "is_updatable": false }, { "name": "statement_descriptor", "type": "string", "regex": "^.{1,13}$", "description": "A text description suitable for a customer's payment statement.", "is_required": false }, { "name": "description", "type": "string", "regex": "^([a-zA-Z]){1,254}$", "description": "Description of the product or service", "is_required": true, "is_updatable": false } ], "is_expirable": true, "is_online": true, "is_refundable": true, "minimum_expiration_seconds": 600, "maximum_expiration_seconds": 604800, "virtual_payment_method_type": null, "is_virtual": false, "multiple_overage_allowed": false, "amount_range_per_currency": [ { "currency": "ISK", "maximum_amount": null, "minimum_amount": null } ], "is_tokenizable": false, "supported_digital_wallet_providers": [], "is_restricted": false, "supports_subscription": false }, { "type": "is_kwp_card", "name": "KWP", "category": "card", "image": "https://iconslib.rapyd.net/checkout/is_kwp_card.png", "country": "is", "payment_flow_type": "", "currencies": [ "ISK" ], "status": 1, "is_cancelable": true, "payment_options": [ { "name": "description", "type": "string", "regex": "", "description": "the description field must be filled in.", "is_required": true, "is_updatable": false }, { "name": "complete_payment_url", "type": "string", "regex": "", "description": "the complete_payment_url field must be filled in.", "is_required": true, "is_updatable": false }, { "name": "error_payment_url", "type": "string", "regex": "", "description": "the error_payment_url field must be filled in.", "is_required": true, "is_updatable": false } ], "is_expirable": false, "is_online": true, "is_refundable": true, "minimum_expiration_seconds": 0, "maximum_expiration_seconds": 0, "virtual_payment_method_type": null, "is_virtual": false, "multiple_overage_allowed": false, "amount_range_per_currency": [ { "currency": "ISK", "maximum_amount": null, "minimum_amount": null } ], "is_tokenizable": false, "supported_digital_wallet_providers": [ "apple_pay" ], "is_restricted": false, "supports_subscription": false }, { "type": "is_mastercard_card", "name": "Mastercard", "category": "card", "image": "https://iconslib.rapyd.net/checkout/is_mastercard_card.png", "country": "is", "payment_flow_type": "", "currencies": [ "ISK" ], "status": 1, "is_cancelable": true, "payment_options": [ { "name": "capture", "type": "boolean", "regex": "", "description": "Determines when the payment is processed for capture.", "is_required": false, "is_updatable": false }, { "name": "complete_payment_url", "type": "string", "regex": "", "description": "the complete_payment_url field must be filled in.", "is_required": true, "is_updatable": false }, { "name": "error_payment_url", "type": "string", "regex": "", "description": "the error_payment_url field must be filled in.", "is_required": true, "is_updatable": false }, { "name": "customer", "type": "string", "regex": "", "description": "ID of a customer object, a string starting with ‘cus_‘. The customer object must contain the fields listed as required, and can contain additional fields listed here.If the customer object does not exist yet, use ‘Create Customer‘", "is_required": false, "is_updatable": false }, { "name": "initiation_type", "type": "string", "regex": "(customer_present|installment|moto|recurring|unscheduled)", "description": "This indicates how the transaction was initiated", "is_required": false, "is_updatable": false } ], "is_expirable": false, "is_online": true, "is_refundable": true, "minimum_expiration_seconds": 0, "maximum_expiration_seconds": 0, "virtual_payment_method_type": null, "is_virtual": false, "multiple_overage_allowed": false, "amount_range_per_currency": [ { "currency": "ISK", "maximum_amount": null, "minimum_amount": null } ], "is_tokenizable": false, "supported_digital_wallet_providers": [ "apple_pay" ], "is_restricted": false, "supports_subscription": false }, { "type": "is_visa_card", "name": "Visa", "category": "card", "image": "https://iconslib.rapyd.nethttps://qaiconslib.rapyd.net/https://qaiconslib.rapyd.net/checkout/is_visa_card.png", "country": "IS", "payment_flow_type": "", "currencies": [ "ISK" ], "status": 1, "is_cancelable": true, "payment_options": [ { "name": "description", "type": "string", "regex": "", "description": "the description field must be filled in.", "is_required": false, "is_updatable": false }, { "name": "capture", "type": "boolean", "regex": "", "description": "Determines when the payment is processed for capture.", "is_required": false, "is_updatable": false }, { "name": "complete_payment_url", "type": "string", "regex": "", "description": "the complete_payment_url field must be filled in.", "is_required": true, "is_updatable": false }, { "name": "error_payment_url", "type": "string", "regex": "", "description": "the error_payment_url field must be filled in.", "is_required": true, "is_updatable": false }, { "name": "customer", "type": "string", "regex": "", "description": "ID of a customer object, a string starting with ‘cus_‘. The customer object must contain the fields listed as required, and can contain additional fields listed here.If the customer object does not exist yet, use ‘Create Customer‘", "is_required": true, "is_updatable": false }, { "name": "ewallet", "type": "string", "regex": "^ewallet_[a-f0-9]{32}$", "conditions": [ { "operator": "$eq", "description": "If the value of the field type is true, ewallet is mandatory field", "element_name": "payment.payment_method_options.aft", "threshold_value": "true" } ], "description": "ID of the wallet that the money is paid into. String starting with ewallet_.", "is_required": false, "is_updatable": false }, { "name": "initiation_type", "type": "string", "regex": "(customer_present|installment|moto|recurring|unscheduled)", "description": "This indicates how the transaction was initiated", "is_required": false, "is_updatable": false } ], "is_expirable": false, "is_online": false, "is_refundable": true, "minimum_expiration_seconds": 0, "maximum_expiration_seconds": 0, "virtual_payment_method_type": null, "is_virtual": false, "multiple_overage_allowed": false, "amount_range_per_currency": [ { "currency": "ISK", "maximum_amount": null, "minimum_amount": null } ], "is_tokenizable": false, "supported_digital_wallet_providers": [ "apple_pay" ], "is_restricted": false, "supports_subscription": false } ] }
Use the Get Payment Method Required Fields with the following parameter:
The data section of this response shows that a Valitor card is the payment method type you will use.
Description of Path Parameters
Path Parameter | Description |
|---|---|
type | Enter is_visa_card as the payment method type. |
Get Payment Method Required Fields Request
Request a set of required fields for a card.
Request
// Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/required_fields/is_visa_card // Message body absent
Get Payment Method Required Fields Response
The response below shows that for a Valitor card, the customer must fill in:
namenumberexpiration_monthexpiration_yearCVV
Response
{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "1afab4a9-2c9e-449b-a36b-a6d4231a1bb9" }, "data": { "type": "is_visa_card", "fields": [ { "name": "token", "type": "string", "regex": "", "is_required": false, "instructions": "" }, { "name": "name", "type": "string", "regex": "", "is_required": true, "instructions": "card holder name" }, { "name": "number", "type": "string", "regex": "", "is_required": true, "instructions": "card number" }, { "name": "expiration_month", "type": "string", "regex": "", "is_required": true, "instructions": "expiration month as string, 01-12" }, { "name": "expiration_year", "type": "string", "regex": "", "is_required": true, "instructions": "expiration year in to digits as string, 18-99" }, { "name": "cvv", "type": "string", "regex": "", "is_required": true, "instructions": "card cvv" }, { "name": "merchant_custom_token", "type": "string", "regex": "", "is_required": false, "instructions": "merchant custom token" }, { "name": "recurrence_type", "type": "string", "regex": "(recurring|installment|unscheduled)", "description": "This indicates the purpose of the token. should be aligned with the subsequent payments using the token.", "is_required": false, "is_updatable": false }, { "name": "network_reference_id", "type": "string", "regex": "", "description": "Network Reference Id", "is_required": false }, { "name": "number_type", "type": "string", "regex": "(fpan|tpan)", "description": "Determining if number is funding PAN or token PAN", "is_required": false } ], "payment_method_options": [ { "name": "3d_required", "type": "boolean", "regex": "", "description": "Allows the client to determine whether the customer is required to complete 3DS authentication for the transaction", "is_required": false, "is_updatable": false }, { "name": "is_korta", "type": "boolean", "regex": "", "description": "", "is_required": false, "is_updatable": false }, { "name": "merchant_ref", "type": "string", "regex": "", "description": "", "is_required": false, "is_updatable": false }, { "name": "3d_version", "type": "String", "regex": "(1.0.2|2.1.0|2.2.0)", "description": "3D Secure version of the transaction.", "is_required": false, "is_updatable": false }, { "name": "cavv", "type": "String", "regex": "", "description": "Cardholder Authentication Verification Value represented as a 20-byte value that is base64 encoded.", "is_required": false, "is_updatable": false }, { "name": "eci", "type": "String", "regex": "(01|02|05|06|07|08)", "description": "Electronic Commerce Indicator (ECI) from MPI Plugin(3-D Secure 1.0) or 3DS Server(3-D Secure 2.0).", "is_required": false, "is_updatable": false }, { "name": "xid", "type": "String", "regex": "", "description": "3D Secure XID, Base64 encoded.Required for VISA 1.0", "is_required": false, "is_updatable": false }, { "name": "ds_trans_id", "type": "String", "regex": "", "description": "The Directory Server (DS) Transaction ID. Required Mastercard 2.0.", "is_required": false, "is_updatable": false }, { "name": "special_features", "type": "string", "regex": "^(crypto)$", "description": "Additional information about the payment. Possible values: crypto - The payment involves cryptocurrency. ", "is_required": false }, { "name": "is_valitor", "type": "boolean", "regex": "", "description": "", "is_required": false, "is_updatable": false }, { "name": "tavv", "type": "String", "regex": "", "description": "Token Authentication Verification Value represented as a 20-byte value that is base64 encoded.", "is_required": false, "is_updatable": false } ], "payment_options": [ { "name": "description", "type": "string", "regex": "", "description": "the description field must be filled in.", "is_required": false, "is_updatable": false }, { "name": "capture", "type": "boolean", "regex": "", "description": "Determines when the payment is processed for capture.", "is_required": false, "is_updatable": false }, { "name": "complete_payment_url", "type": "string", "regex": "", "description": "the complete_payment_url field must be filled in.", "is_required": true, "is_updatable": false }, { "name": "error_payment_url", "type": "string", "regex": "", "description": "the error_payment_url field must be filled in.", "is_required": true, "is_updatable": false }, { "name": "is_korta", "type": "boolean", "regex": "", "description": "", "is_required": false, "is_updatable": false }, { "name": "customer", "type": "string", "regex": "", "description": "ID of a customer object, a string starting with cus_. The customer object must contain the fields listed as required, and can contain additional fields listed here.If the customer object does not exist yet, use Create Customer", "is_required": true, "is_updatable": false } ], "minimum_expiration_seconds": 60, "maximum_expiration_seconds": 604800 } }
See Create Payment for more detailed information about the fields and objects used in the request.
Description of Body Parameters
Body Parameter | Description |
|---|---|
amount | Enter 250 as the payment amount. |
currency | Enter USD as the currency code. |
capture | Enter true as the value. This tells Rapyd to collect the payment for you right away. If 'false', a hold will be put on the card and the funds will not be captured until the status is updated. |
Object Fields
Include the payment_method object and payment_method_options object in the body of the request.
Object | Field | Description |
|---|---|---|
payment_method | type | Enter is_visa_card as the type |
payment_method | name | Enter Visa Card Test as the name |
payment_method | number | Enter 5186151969991591 as the card number |
payment_method | expiration_month | Enter 12 as the expiration month |
payment_method | expiration_year | Enter 30 as the expiration year |
payment_method | cvv | Enter 123 |
payment_method | number_type | Indicates if the number field contains a card token or a regular card number. Two possible values:
Enter TPAN as the value when using a network token for the payment. |
payment_method_options | tavv | Enter AIwq5CHaXx1uAD09xomcAAADFA==
|
Create Payment Request
Request
// Request URL: POST https://sandboxapi.rapyd.net/v1/payments // Message body: { "amount": 250, "currency": "USD", "capture": true, "description": "visa demo 3", "initiation_type": "customer_present", "payment_method": { "type": "is_visa_card", "fields": { "name": "Visa Card Test", "number": "5186151969991591", "expiration_month": "12", "expiration_year": "30", "number_type": "TPAN" } }, "payment_method_options": { "cavv": "kBMcQDw42rjEKBDCA/WQw5eBlMGf", "eci": "02", "ds_trans_id": "8a567e19-8580-49bd-a5e5-2d6bc1924602", "tavv": "AIwq5CHaXxluAD09xomcAAADFA==" }, "complete_payment_url": "https://www.rapyd.net", "error_payment_url": "https://www.docs.rapyd.net" }
Create Payment Response
Response
{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "a3ff86a3-f045-4806-9e32-8c3c99c2c820" }, "data": { "id": "payment_1d022d3ff321baf483525253072d3943", "amount": 250, "original_amount": 250, "is_partial": false, "currency_code": "USD", "country_code": "IS", "status": "CLO", "description": "visa demo 3", "merchant_reference_id": "", "customer_token": "cus_b3c1bd3012ea414219fd95243c0803b0", "payment_method": "card_fb413caa11dd94e3bcffb0dff24f6290", "payment_method_data": { "id": "card_fb413caa11dd94e3bcffb0dff24f6290", "type": "is_visa_card", "category": "card", "metadata": null, "image": "", "webhook_url": "", "supporting_documentation": "", "next_action": "not_applicable", "name": "Visa Card Test", "last4": "1591", "acs_check": "unchecked", "cvv_check": "unchecked", "bin_details": { "type": null, "brand": null, "level": null, "issuer": null, "country": null, "bin_number": "518615" }, "number_type": "TPAN", "expiration_year": "30", "expiration_month": "12", "fingerprint_token": "ocfp_180e9479ba47ac71fb88dcf719e88234", "network_reference_id": "ABC8791471120" }, "auth_code": "794487", "expiration": 1701085308, "captured": true, "refunded": false, "refunded_amount": 0, "receipt_email": "", "redirect_url": "", "complete_payment_url": "https://www.rapyd.net", "error_payment_url": "https://www.docs.rapyd.net", "receipt_number": "", "flow_type": "", "address": null, "statement_descriptor": "ARMONICCI", "transaction_id": "", "created_at": 1700480507, "metadata": {}, "failure_code": "", "failure_message": "", "paid": true, "paid_at": 1700480519, "dispute": null, "refunds": null, "order": null, "outcome": null, "visual_codes": {}, "textual_codes": {}, "instructions": {}, "ewallet_id": "ewallet_cada587d3a817b42fca2c6ba63ac1d1b", "ewallets": [ { "ewallet_id": "ewallet_cada587d3a817b42fca2c6ba63ac1d1b", "amount": 250, "percent": 100, "refunded_amount": 0 } ], "payment_method_options": { "eci": "02", "cavv": "kBMcQDw42rjEKBDCA/WQw5eBlMGf", "ds_trans_id": "8a567e19-8580-49bd-a5e5-2d6bc1924602" }, "payment_method_type": "is_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": "mid_63e991ad4ba1a1508ffa8df196c0b8e3", "next_action": "not_applicable", "error_code": "", "remitter_information": {}, "save_payment_method": true } }
The response shows that Rapyd successfully processed the payment based on the amount, currency, and payment method.
The payment is successful since the status is CLO (closed).
You can now notify your customer that the purchase is complete.