--- title: "Card Payments" source_url: https://docs.rapyd.net/en/card-payments.html lang: en --- # Card Payments Securely accept international and local, credit and debit card payments across the globe. A card payment is initiated when your customer selects card payment from your list of payment methods, or enters their card details into your card form fields. A card payment initiation consists of the following: - Authorization amount. - Successful [capture](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_capture "Capture") of the authorized transaction. By default, all card payments are captured immediately after authorization, but sometimes, a post-capture process can be used to put funds on hold. The card payment process below explains how to: - Add local and international card payments to your checkout. - Complete a single card payment authorization. - Capture the transaction. ### Card Payments Workflow Finding the specific card payment methods you'll accept and the corresponding required fields that customers fill out is described under How it Works. ![card-payment-workflow.jpg](image/img-ac3af5f46511a228641d1e3f51be5fa8.png) 1. The customer completes the card payment in checkout on your website. 2. Third-party token provider requests a network token. 3. You request Rapyd to process the card payment using a network token. 4. Rapyd processes the payment and sends the response and webhook back to you. 5. You display your purchase success page to the customer. > **Note:** > > Only clients with [PCI-DSS](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_dss "Payment Card Industry Data Security Standard") certification can handle personal identifying information for cards. This method is available to merchants who have signed a special agreement with Rapyd. ### How Card Payments Work ### Find Available Payment Methods Decide the card payment types you'll accept in a chosen country. Use [List Payment Methods by Country](https://docs.rapyd.net/en/list-payment-methods-by-country.md "List Payment Methods by Country") with the following parameters: - GB and GBP are used for country and currency in the sample codes below. GB Visa Card as the payment type. Description of Query Parameters | Query Parameter | Description | | --- | --- | | country | Enter **GB** as the country code. | | currency | Enter **GBP** as the currency code. | ### List Payment Methods by Country Request - - Request - ``` // Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/country?country=GB¤cy=GBP // Message body absent ``` - - .NET Core - ``` using System; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { string result = RapydApiRequestSample.Utilities.MakeRequest("GET", "/v1/payment_methods/country?country=GB¤cy=GBP"); Console.WriteLine(result); } catch (Exception e) { Console.WriteLine("Error completing request: " + e.Message); } } } } ``` - - JavaScript - ``` const makeRequest = require('/utilities').makeRequest; async function main() { try { const result = await makeRequest('GET', '/v1/payment_methods/country?country=GB¤cy=GBP'); console.log(result); } catch (error) { console.error('Error completing request', error); } } ``` - - PHP - ``` /utilities.php"; include($path); try { $object = make_request('get', '/v1/payment_methods/country?country=GB¤cy=GBP'); var_dump($object); } catch (Exception $e) { echo "Error: $e"; } ?> ``` - - Python - ``` from pprint import pprint from utilities import make_request country = 'GB' currency = 'GBP' results = make_request(method='get', path=f'/v1/payment_methods/country?country={country}¤cy={currency}') pprint(results) ``` ### List Payment Methods by Country Response - - Response - ``` { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "cfa35a73-aa0b-4e7e-839c-4c3b6149edd7" }, "data": [{ "type": "gb_visa_card", "name": "Visa", "category": "card", "image": "https://iconslib.rapyd.net/checkout/gb_visa_card.png", "country": "GB", "payment_flow_type": "", "currencies": [ "AED", "AUD", "BGN", "BOB", "BRL", "CHF", "CNY", "COP", "CZK", "DKK", "EUR", "GBP", "GEL", "HKD", "HRK", "HUF", "IDR", "ILS", "INR", "ISK", "JPY", "KZT", "MDL", "MXN", "MYR", "NOK", "NZD", "PEN", "PHP", "PLN", "RON", "RSD", "RUB", "SEK", "SGD", "THB", "TRY", "TWD", "UAH", "USD", "UYU", "ZAR" ], "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": false, "is_updatable": false } ], "is_expirable": true, "is_online": false, "is_refundable": true, "minimum_expiration_seconds": 600, "maximum_expiration_seconds": 604800, "virtual_payment_method_type": "card", "is_virtual": false, "multiple_overage_allowed": false, "amount_range_per_currency": [ { "currency": "AED", "maximum_amount": null, "minimum_amount": null }, { "currency": "AUD", "maximum_amount": null, "minimum_amount": null }, { "currency": "BGN", "maximum_amount": null, "minimum_amount": null }, { "currency": "BOB", "maximum_amount": null, "minimum_amount": null }, { "currency": "BRL", "maximum_amount": null, "minimum_amount": null }, { "currency": "CHF", "maximum_amount": null, "minimum_amount": null }, { "currency": "CNY", "maximum_amount": null, "minimum_amount": null }, { "currency": "COP", "maximum_amount": null, "minimum_amount": null }, { "currency": "CZK", "maximum_amount": null, "minimum_amount": null }, { "currency": "DKK", "maximum_amount": null, "minimum_amount": null }, { "currency": "EUR", "maximum_amount": null, "minimum_amount": null }, { "currency": "GBP", "maximum_amount": null, "minimum_amount": null }, { "currency": "GEL", "maximum_amount": null, "minimum_amount": null }, { "currency": "HKD", "maximum_amount": null, "minimum_amount": null }, { "currency": "HRK", "maximum_amount": null, "minimum_amount": null }, { "currency": "HUF", "maximum_amount": null, "minimum_amount": null }, { "currency": "IDR", "maximum_amount": null, "minimum_amount": null }, { "currency": "ILS", "maximum_amount": null, "minimum_amount": null }, { "currency": "INR", "maximum_amount": null, "minimum_amount": null }, { "currency": "ISK", "maximum_amount": null, "minimum_amount": null }, { "currency": "JPY", "maximum_amount": null, "minimum_amount": null }, { "currency": "KZT", "maximum_amount": null, "minimum_amount": null }, { "currency": "MDL", "maximum_amount": null, "minimum_amount": null }, { "currency": "MXN", "maximum_amount": null, "minimum_amount": null }, { "currency": "MYR", "maximum_amount": null, "minimum_amount": null }, { "currency": "NOK", "maximum_amount": null, "minimum_amount": null }, { "currency": "NZD", "maximum_amount": null, "minimum_amount": null }, { "currency": "PEN", "maximum_amount": null, "minimum_amount": null }, { "currency": "PHP", "maximum_amount": null, "minimum_amount": null }, { "currency": "PLN", "maximum_amount": null, "minimum_amount": null }, { "currency": "RON", "maximum_amount": null, "minimum_amount": null }, { "currency": "RSD", "maximum_amount": null, "minimum_amount": null }, { "currency": "RUB", "maximum_amount": null, "minimum_amount": null }, { "currency": "SEK", "maximum_amount": null, "minimum_amount": null }, { "currency": "SGD", "maximum_amount": null, "minimum_amount": null }, { "currency": "THB", "maximum_amount": null, "minimum_amount": null }, { "currency": "TRY", "maximum_amount": null, "minimum_amount": null }, { "currency": "TWD", "maximum_amount": null, "minimum_amount": null }, { "currency": "UAH", "maximum_amount": null, "minimum_amount": null }, { "currency": "USD", "maximum_amount": null, "minimum_amount": null }, { "currency": "UYU", "maximum_amount": null, "minimum_amount": null }, { "currency": "ZAR", "maximum_amount": null, "minimum_amount": null } ], "is_tokenizable": false, "supported_digital_wallet_providers": [ "google_pay" ], "is_restricted": false, "supports_subscription": true }, } ] } ``` ### Get the Required Fields for the Payment Method Types Use the [Get Payment Method Required Fields](https://docs.rapyd.net/en/get-payment-method-required-fields.md "Get Payment Method Required Fields") with the following parameter: The `data` section of this response shows that a Visa card is an acceptable payment method type. **Note**: A real response usually lists many payment types. Description of Path Parameters | Path Parameter | Description | | --- | --- | | type | Enter **gb_visa_card** as the payment method type. | ### Get Payment Method Required Fields Request Request a set of required fields for a Visa card. - - Request - ``` // Request URL: GET https://sandboxapi.rapyd.net/v1/payment_methods/gb_visa_card/required_fields // Message body absent ``` - - .NET Core - ``` using System; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { string result = RapydApiRequestSample.Utilities.MakeRequest("GET", "/v1/payment_methods/gb_visa_card/required_fields"); Console.WriteLine(result); } catch (Exception e) { Console.WriteLine("Error completing request: " + e.Message); } } } } ``` - - JavaScript - ``` const makeRequest = require('/utilities').makeRequest; async function main() { try { const result = await makeRequest('GET', '/v1/payment_methods/gb_visa_card/required_fields'); console.log(result); } catch (error) { console.error('Error completing request', error); } } ``` - - PHP - ``` /utilities.php"; include($path); try { $object = make_request('get', '/v1/payment_methods/gb_visa_card/required_fields'); var_dump($object); } catch (Exception $e) { echo "Error: $e"; } ?> ``` - - Python - ``` from pprint import pprint from utilities import make_request payment_method = 'gb_visa_card' results = make_request(method='get', path=f'/v1/payment_methods/{payment_method}/required_fields') pprint(results) ``` ### Get Payment Method Required Fields Response The response below shows that for a GB Visa card, the customer must fill in: - `number` - `expiration_month` - `expiration_year` - `name` - `CVV` - - Response - ``` { “status”: { “error_code”: “”, “status”: “SUCCESS”, “message”: “”, “response_code”: “”, “operation_id”: “598b1a00-e302-4037-b0ef-aac895974e9e” }, “data”: { “type”: “gb_visa_card”, “fields”: [ { “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”: false, “instructions”: “card cvv” }, { “name”: “name”, “type”: “string”, “regex”: “”, “is_required”: false, “instructions”: “card holder name” }, { “name”: “address”, “type”: “Address”, “regex”: “”, “is_required”: false, “instructions”: “card billing address. see Address object for more details” } ], “payment_method_options”: [ { “name”: “3d_required”, “type”: “string”, “regex”: “”, “description”: “”, “is_required”: false, “is_updatable”: false } ], “payment_options”: [ { “name”: “customer”, “type”: “customer”, “regex”: “”, “description”: “make sure a customer was created with first_name, last_name and email”, “is_required”: true, “is_updatable”: false } ], “minimum_expiration_seconds”: null, “maximum_expiration_seconds”: null } } ``` ### Accept a Card Payment From a Customer **Note**: For 3DS flow see [Card Payment With 3DS Verification](https://docs.rapyd.net/en/card-payment-with-3ds-verification.md "Card Payment With 3DS Verification") ### Initiate Your Customer's Payment Collect a payment from your customer: Description of Body Parameters | Body Parameter | Description | | --- | --- | | payment_method | Enter an object with the following fields: `type` - **gb_visa_card** `fields` - Enter an object with the following fields: - `number` - **4111111111111111** - `expiration_month` - **10** - `expiration_year` - **29** - `cvv` - **123** | | amount | Enter **9.99** as the payment amount. | | currency | Enter **GBP** 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. | | is_adjustable | Set the value to **true** to initiate a preauthorization. | ### Adjustable Authorizations for Card Payments A merchant can use an adjustable authorization for a customer-initiated card payment when the final charge is unknown at the start of the transaction. The authorization will expire after 30 days. Use [Create Payment](https://docs.rapyd.net/en/create-payment.md "Create Payment") for the transactions. Under the `payment_method_options` object in the request body, set the `is_adjustable` field to `true`. This will initiate a preauthorization for the card payment. The merchant needs to be configured to be able to create adjustable payments. If the final amount is lower, then capture the lower amount. If the final amount is higher, then an [Update Payment](https://docs.rapyd.net/en/update-payment.md "Update Payment") request will need to be made. This is only possible if `is_adjustable` is set to `true`. Then capture the final amount. ### AVS Check (Address Verification) When creating a card payment, the merchant can perform an AVS check. The check is to see if the cardholder’s address matches the address on file with the card issuer. This can help to reduce fraudulent transactions. Use [Create Payment](https://docs.rapyd.net/en/create-payment.md "Create Payment") for the transaction. Under the `payment_method_options` object in the request body, set the `avs_required` field to `true`. Then include the `address` object in the payment request. See [Create Payment](https://docs.rapyd.net/en/create-payment.md "Create Payment") for information about the `address` object. ### Submit Payment to Rapyd Rapyd processes your customer's card payment and immediately captures the funds for you (in the sample code below, the amount used is 9.99 GBP). ### Create Payment Request - - Request - ``` // Request URL: POST https://sandboxapi.rapyd.net/v1/payments // Message body: { "amount": 9.99, "currency": "GBP", "payment_method": { "type": "gb_visa_card", "fields": { "number": "4111111111111111", "expiration_month": "10", "expiration_year": "29", "cvv": "123" } }, "error_payment_url": "https://error_example.net", "capture": true } ``` - - .NET Core - ``` using System; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { string payment = @"{""amount"":9.99,""currency"":""GBP"",""payment_method"":{""type"":""gb_visa_card"",""fields"":{""number"":""4111111111111111"",""expiration_month"":""10"",""expiration_year"":""29"",""cvv"":""123""}},""error_payment_url"":""https:error_example.net"",""capture"":true}"; string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/payments", payment); Console.WriteLine(result); } catch (Exception e) { Console.WriteLine("Error completing request: " + e.Message); } } } } ``` - - JavaScript - ``` const makeRequest = require('/utilities').makeRequest; async function main() { try { const body = { amount: 9.99, currency: 'GBP', payment_method: { type: 'gb_visa_card', fields: { number: '4111111111111111', expiration_month: '10', expiration_year: '29', cvv: '123' } }, capture: true }; const result = await makeRequest('POST', '/v1/payments', body); console.log(result); } catch (error) { console.error('Error completing request', error); } } ``` - - PHP - ``` /utilities.php"; include($path); $body = [ 'amount' => 9.99, 'currency' => 'GBP', 'payment_method' => [ 'type' => 'gb_visa_card', 'fields' => [ 'number' => '4111111111111111', 'expiration_month' => '10', 'expiration_year' => '29', 'cvv' => '123'] ], 'error_payment_url' => urldecode('https://error_example.net'), 'capture' => true ]; try { $object = make_request('post', '/v1/payments', $body); var_dump($object); } catch (Exception $e) { echo "Error: $e"; } ?> ``` - - Python - ``` from pprint import pprint from utilities import make_request payment_body = { 'amount': 9.99, 'currency': 'GBP', 'payment_method': { 'type': 'gb_visa_card', 'fields': { 'number': '4111111111111111', 'expiration_month': '10', 'expiration_year': '29', 'cvv': '123' } }, 'error_payment_url': 'https://error_example.net', 'capture': True } results = make_request(method='post', path='/v1/payments', body=payment_body) pprint(results) ``` ### Create Payment Response - - Response - ``` { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "d036678e-79f3-45fd-ac9b-54277a0f1887" }, "data": { "id": "payment_476c494ba433285e3468ddd3d12e6287", "amount": 9.99, "original_amount": 9.99, "is_partial": false, "currency_code": "GBP", "country_code": "GB", "status": "CLO", // ... "customer_token": "cus_f7f818996c5cff475839fc2b5edf985a", "payment_method": "card_1bdfe1b70af665004da098f8bd859282", "expiration": 0, "captured": true, // ... "error_payment_url": "https://error_example.net", // ... "created_at": 1581235148, // ... "paid": true, "paid_at": 1581235148, // ... "payment_method_type": "gb_visa_card", "payment_method_type_category": "card", // ... } } ``` The response shows that Rapyd successfully processed the payment based on the amount, currency, and payment method. The payment is successful since the `status` (under `data`) is **CLO** (closed). You can now notify your customer that the purchase is complete.