Card Payments and Merchant Initiated Transactions
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 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.
Merchant Initiated Transactions (MIT) are card transactions that are initiated by the merchant, where the cardholder is not present.
For certain payment method types, you can include the initiation_type field in the request. This allows you to reauthorize a card payment, or capture funds at a later date.
Merchants can initiate card transactions with the card scheme under specific circumstances. These situations involve the merchant needing to charge service fees, or extend an authorization for a card on file. The capture of funds may take place days to weeks after the initial payment, and are initiated without the cardholder being present.
The following use cases below will demonstrate the importance of initiation types for no show, delayed charges, and reauthorizations for card payments across a variety of industries.
No Show
A no show occurs when a customer fails to arrive for an agreed-upon service, such as a hotel reservation or a car rental. This scenario demonstrates the transition from a Customer Initiated Transaction (CIT) to a Merchant Initiated Transaction (MIT).
A customer books a one-night hotel stay online. During checkout, they provide their card details and agree to a cancellation policy stating that "no-shows" will be charged for the first night. At this stage, the merchant may perform a pre-authorization to verify funds or simply store the card as a Credential on File (CoF).
The customer fails to arrive on the scheduled check-in date and does not cancel the reservation.Since the customer is not present to swipe their card or provide a new signature, the merchant must initiate the charge. If a previous authorization exists but the merchant needs to process a specific penalty amount, or if the original hold has expired, the merchant sends a new transaction request.
This request includes the initiation_type: no_show and references the original_payment ID from the booking.
Delayed Charges
A delayed charge is when a charge is submitted after the primary service has concluded.
A guest checks into a hotel for a three-night stay. At check-in, the hotel performs a standard authorization for the cost of the room and tax. The guest's stay proceeds normally, and they check out without visiting the front desk.
After the guest checks out, the hotel's housekeeping staff inspects the room and finds that the guest consumed several items from the minibar and ordered a movie on the TV. These charges, totaling $75, were not included in the initial room charge because they occurred after the initial payment was processed and the guest had already left.
Since the guest agreed to the hotel's terms and conditions at check-in (which grants the hotel the right to charge for incidentals), the hotel's system can now perform a merchant-initiated delayed charge. The hotel's system sends a new transaction request for $75 to the payment gateway. The transaction is flagged as a "delayed charge" and references the original authorization or card-on-file token. This charge is processed without a new card swipe or the cardholder's presence.
The charge is a delayed charge because it is submitted after the primary service (the hotel stay) has concluded and the guest has left. The timing of the charge is not synchronized with the service itself. The charge is merchant-initiated because the charge is initiated by the hotel's system, not by the customer (who is no longer present to swipe their card). It relies on the pre-existing agreement and the card details stored "on file."
This process is critical for businesses with unpredictable post-service charges. It allows them to collect revenue for services used without requiring the customer to be physically present for a final transaction.
Reauthorization
A reauthorization is where the original authorization for a payment has expired, but the service or product delivery is not quite complete. This allows the merchant to re-secure funds without the customer having to be present. The most common use cases are related to extended timelines for services or delivery.
Split or Delayed Shipment
A customer places an order for multiple items from an online retailer. The total value of the order is $300. The retailer's system performs a single authorization for the full amount. A hold of $300 is placed on the customer's card. This is typically valid for 5-7 days.
It turns out one of the items is on backorder and won't be available to ship for another two weeks. The retailer needs to capture the funds for the first shipment now, but also needs to ensure the funds are still available for the second shipment later, after the initial authorization has expired.
The merchant captures the funds for the first shipment (e.g., $150) from the original authorization. As the expiration date for the original authorization approaches, the merchant's system automatically initiates a reauthorization merchant-initiated transaction (MIT) for the remaining balance ($150). The reauthorization request is sent to the issuing bank, which places a new authorization hold on the card for $150. This is processed as a merchant-initiated transaction because the customer is not actively participating in the transaction.
This new authorization is valid for another 5-7 days, securing the funds until the second shipment is ready to be delivered and captured.
Extended Vehicle Rental
A customer initially rents a luxury car for a long-term, 45-day lease. The rental company's policy is to perform a pre-authorization for the full, known amount of the lease plus a security deposit, totaling $15,000.
At the beginning of the rental period, the rental company performs a pre-authorization for $15,000. This hold is valid for a maximum of 30 days, as per the card network rules for this merchant category code (MCC).
The customer is still in possession of the vehicle after 30 days. The original $15,000 pre-authorization is about to expire. The rental company needs to maintain a valid authorization on the card to ensure funds are secured for the remaining 15 days of the rental period.
As the 30-day expiration date of the original authorization approaches, the rental company's system automatically initiates a reauthorization merchant-initiated transaction (MIT). The system sends a new request to the issuing bank for the same $15,000 amount. This is explicitly flagged as a reauthorization.
The issuing bank approves the new authorization request, and a fresh 30-day hold is placed on the card for $15,000. This is processed as a merchant-initiated transaction because the customer is not present to swipe their card again.
At the end of the 45-day rental period, the rental company captures the final, agreed-upon amount from the last valid authorization.
This example highlights a legitimate reason for using a reauthorization MIT: to maintain a secure hold on a customer's funds for a service that extends beyond the maximum allowed duration of a single authorization.
The customer completes the card payment in checkout on your website.
Third-party token provider requests a network token.
You request Rapyd to process the card payment using a network token.
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:
AT and GBP are used for country and currency in the sample codes below. The payment method type used is at_visa_card.
Description of Query Parameters
Query Parameter | Description |
|---|---|
country | Enter AT as the country code. AT is the ISO country code for Austria. |
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?currency=GBP&country=AT // Message body absent
List Payment Methods by Country Response
Response
{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "01f4860c-9eb4-41d6-8ef8-a62b0872ccc3" }, "data": [ { "type": "at_amex_pos", "name": "AustriaAmex POS PMT", "category": "pos", "image": "", "country": "AT", "payment_flow_type": "", "currencies": [ "GBP" ], "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": "statement_descriptor", "type": "string", "regex": "", "description": "A text description suitable for a customer's payment statement. 5-22 characters.", "is_required": true, "is_updatable": false }, { "name": "ewallet", "type": "string", "regex": "^ewallet_[a-f0-9]{32}$", "description": "ID of the wallet that the money is paid into. String starting with ewallet_.", "is_required": true, "is_updatable": false }, { "name": "initiation_type", "type": "string", "regex": "(card_present|customer_present|installment|moto|recurring|unscheduled)", "description": "How the transaction was initiated.", "is_required": false, "is_updatable": false }, { "name": "device_id", "type": "string", "regex": "", "description": "Unique ID from POS provider.", "is_required": true, "is_updatable": false }, { "name": "payment_advice", "type": "object", "regex": "", "description": "Raw JSON from POS device.", "is_required": true, "is_updatable": false } ], "is_expirable": true, "is_online": false, "is_refundable": true, "minimum_expiration_seconds": 0, "maximum_expiration_seconds": 2592000, "virtual_payment_method_type": null, "is_virtual": false, "multiple_overage_allowed": false, "amount_range_per_currency": [ { "currency": "GBP", "maximum_amount": null, "minimum_amount": null } ], "is_tokenizable": false, "supported_digital_wallet_providers": [], "is_restricted": false, "supports_subscription": false, "supports_aft": false }, { "type": "at_mastercard_card", "name": "Mastercard", "category": "card", "image": "https://iconslib.rapyd.net/checkout/at_mastercard_card.png", "country": "AT", "payment_flow_type": "", "currencies": [ "GBP" ], "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": 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": true, "is_online": false, "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": "GBP", "maximum_amount": null, "minimum_amount": null } ], "is_tokenizable": false, "supported_digital_wallet_providers": [], "is_restricted": false, "supports_subscription": true, "supports_aft": true }, { "type": "at_visa_card", "name": "Visa", "category": "card", "image": "https://iconslib.rapyd.net/checkout/at_visa_card.png", "country": "AT", "payment_flow_type": "", "currencies": [ "GBP" ], "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": 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": true, "is_online": false, "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": "GBP", "maximum_amount": null, "minimum_amount": null } ], "is_tokenizable": false, "supported_digital_wallet_providers": [], "is_restricted": false, "supports_subscription": true, "supports_aft": true } ] }
Use the 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.
Description of Path Parameters
Path Parameter | Description |
|---|---|
type | Enter at_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/required_fields/at_visa_card // Message body absent
Get Payment Method Required Fields Response
The response below shows that for an AT Visa card, the customer must fill in:
numberexpiration_monthexpiration_yearnameCVV
Response
{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "2193102d-5730-4fc5-af45-62105389c05b" }, "data": { "type": "at_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": true, "instructions": "card cvv" }, { "name": "name", "type": "string", "regex": "", "is_required": true, "instructions": "card holder name" }, { "name": "network_reference_id", "type": "string", "regex": "", "description": "Network Reference Id", "is_required": false }, { "name": "recurrence_type", "type": "string", "regex": "(recurring|installment|unscheduled)", "description": "Indicates how the token will be used. Required when this payment method is added to the customer profile. Values: 'unscheduled'=Individual unrelated payments. 'installment'=Regular payments for a defined number of payment cycles. 'recurring'=Regular payments for an indefinite period.", "is_required": false, "is_updatable": 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": "aft", "type": "boolean", "regex": "", "description": "Allows the client to determine whether the request is an AFT request", "is_required": false, "is_updatable": false }, { "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": "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": "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 }, { "name": "cvv", "type": "string", "regex": "", "description": "Card CVV for Subsequent Payments", "is_required": false, "is_updatable": false }, { "name": "currency", "type": "string", "regex": "", "description": "Three-letter ISO 4217 code, defines the currency of the transaction.", "is_required": false, "is_updatable": false }, { "name": "special_condition_indicator", "type": "String", "regex": "", "description": "Indicator of transactions that are considered high risk, e.g. the purchase of cryptocurrency.", "is_required": false, "is_updatable": false }, { "name": "purpose_code", "type": "string", "regex": "(family_support|regular_labor_transfers|travel_and_tourism|education|hospitalization_and_medical_treatment|emergency_need|savings|gifts|other|salary|crowd_lending|crypto_currency|high_risk_securities)", "description": "The code that identifies the reason for the transaction. Required only for AFT transactions.", "is_required": false, "is_updatable": false }, { "name": "sca_exemption", "type": "string", "regex": "(low_value|transaction_risk_analysis|authentication_outage|secure_corporate_payments)", "description": "Request a strong customer authentication (SCA) exemption from 3D Secure (3DS) authentication for a merchant of a payment facilitator (PayFac). Specify one exemption type. To enable this feature, contact Rapyd Client Support.", "is_required": false, "is_updatable": false }, { "name": "is_direct_purchase", "type": "boolean", "regex": "", "description": "The merchant to specify if its wallet load or a direct purchase.", "is_required": false, "is_updatable": 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": "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 } ], "minimum_expiration_seconds": 600, "maximum_expiration_seconds": 604800 }
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:
|
amount | Enter 50 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. |
initiation_type | Enter one of the following values:
|
Submit Payment to Rapyd
Rapyd processes your customer's card payment and immediately captures the funds for you.
Create Payment Request
Request
// Request URL: POST https://sandboxapi.rapyd.net/v1/payments // Message body: { "amount": 50, "currency": "GBP", "capture": true, "save_payment_method": true, "original_payment": "payment_6878e51a572cd5450062028b52957220", "initiation_type": "no_show", "payment_method": { "type": "at_visa_card", "fields": { "number": "4111111111111111", "expiration_month": "12", "expiration_year": "25", "cvv": "123", "name": "John Doe" } }, "complete_payment_url": "https://complete.rapyd.net", "error_payment_url": "https://error.rapyd.net" }
Create Payment Response
Response
{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "a313e62b-ea89-4690-a22b-f04172c79f85" }, "data": { "id": "payment_f7d78165bed5ac105ead1499b1633f71", "amount": 50, "original_amount": 50, "is_partial": false, "currency_code": "GBP", "country_code": "AT", "status": "CLO", "description": "", "merchant_reference_id": "", "customer_token": "cus_40a77ebd45ff40b83161e60ea602ce66", "payment_method": "card_e15fee15b3ff0cc14cfceedc18093281", "payment_method_data": { "id": "card_e15fee15b3ff0cc14cfceedc18093281", "type": "at_visa_card", "category": "card", "metadata": null, "image": "", "webhook_url": "", "supporting_documentation": "", "next_action": "not_applicable", "name": "John Doe", "last4": "1111", "acs_check": "unchecked", "cvv_check": "pass", "bin_details": { "type": "DEBIT", "brand": "VISA", "level": "GOLD", "issuer": "INTL HDQTRS-CENTER OWNED", "country": "SG", "bin_number": "411111" }, "expiration_year": "25", "expiration_month": "12", "fingerprint_token": "ocfp_b8eafaeeea548e97ef23914cffa7154a", "network_reference_id": "00000******2", "payment_account_reference": "V0010013018036782991622965076" }, "auth_code": 823886, "expiration": 17623******00, "captured": true, "refunded": false, "refunded_amount": 0, "receipt_email": "", "redirect_url": "", "complete_payment_url": "https://complete.rapyd.net", "error_payment_url": "https://error.rapyd.net", "receipt_number": "", "flow_type": "", "address": null, "statement_descriptor": "merchant-1", "transaction_id": "", "created_at": 17618******63, "metadata": {}, "failure_code": "", "failure_message": "", "paid": true, "paid_at": 17618******64, "dispute": null, "refunds": null, "order": null, "outcome": null, "visual_codes": {}, "textual_codes": {}, "instructions": [], "ewallet_id": "ewallet_6f288d7c178f545ebb56be8990ff0ff2", "ewallets": [ { "ewallet_id": "ewallet_6f288d7c178f545ebb56be8990ff0ff2", "amount": 50, "percent": 100, "refunded_amount": 0 } ], "payment_method_options": { "3d_required": false }, "payment_method_type": "at_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": "no_show", "mid": "mid_1ab3788e7e7e423ea990a48073d8b2b1", "next_action": "not_applicable", "error_code": "", "remitter_information": {}, "save_payment_method": true, "merchant_advice_code": null, "merchant_advice_message": null, "payment_request_id": null, "transaction_link_id": null, "original_payment": "payment_6878e51a572cd5450062028b52957220" } }
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.