Skip to main content

Documentation

Add Payment Method to Customer

Add a payment method to a customer profile (card on file).

Prerequisites

Use Get Payment Method Required Fields to determine which fields are required to create the payment method.

In the sandbox, adding a card payment method type (with the type field and the fields object) requires 3DS authentication by the cardholder. See Simulating 3DS Authentication. In production, requirements differ from card to card. 3DS authentication is required if payment_method_options.3d_required is set to true or if the bank or card network require it.

This method triggers the Customer Payment Method Created Webhook. This webhook contains the same information as the response.

In addition, when a card payment method type is added to a customer:

The following asynchronous webhooks provide information about later changes to the Payment Method object:

Note

  • Merchants who have PCI clearance can use the API to add a card payment method.

  • You can also use a hosted page to add a card payment method to a customer. See Create Card Token.

  • Use this method to create a payment method ID for a subscription. See Create Subscription.

  • Use this method to create a network reference ID for repeat card payments. See Customer Payment Method. You can also create a network reference ID when you create a payment. See Create Payment.

    • customer

    • ID of the customer. String starting with cus_.

Code Samples
    • .NET

      • using System;
        using System.Text.Json;
        
        namespace RapydApiRequestSample
        {
            class Program
            {
                static void Main(string[] args)
                {
                    try
                    {
                        string[] payment_method_type_categories = new string[] { "cash", "bank_redirect", "bank_transfer" };
                        string customerId = "cus_7b4cd1f607a0b5df13eb1871834c4480";
        
                        var metadata = new { merchant_defined = true };
        
                        var requestObj = new
                        {
                            type = "nl_iban_bank",
                            metadata = new
                            {
                                merchant_defined = true
                            }
                        };
        
                        string request = JsonSerializer.Serialize(requestObj);
        
                        string result = RapydApiRequestSample.Utilities.MakeRequest("POST", $"/v1/customers/{customerId}/payment_methods", request);
        
                        Console.WriteLine(result);
                    }
                    catch (Exception e)
                    {
                        Console.WriteLine("Error completing request: " + e.Message);
                    }
                }
            }
        }
        
    • JavaScript

      • const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;
        
        async function main() {
          try {
            const body = {
              type: 'nl_iban_bank',
              fields: {}
            };
            const result = await makeRequest(
              'POST',
              '/v1/customers/cus_f3923ec56a56578b6a18df24d4f32d54/payment_methods',
              body
            );
        
            console.log(result);
          } catch (error) {
            console.error('Error completing request', error);
          }
        }
    • PHP

      • <?php
        $path = $_SERVER['DOCUMENT_ROOT'];
        $path .= "/<path-to-your-utility-file>/utilities.php";
        include($path);
        
        $body = [
            "type" => "nl_iban_bank",
        ];
        
        try {
            $object = make_request('post', "/v1/customers/cus_5861b2ec3e7441bfd43756bb491ddf10/payment_methods", $body);
            var_dump($object);
        } catch (Exception $e) {
            echo "Error: $e";
        }
        ?>
    • Python

      • from pprint import pprint
        
        from utilities import make_request
        
        payment_method = {
            "type": "nl_iban_bank",
            "fields": {},
            "metadata": {
                "merchant_defined": True
            }
        }
        result = make_request(method='post',                     path='/v1/customers/cus_0645ee52e91ed51f30176e727b9acfaa/payment_methods',
                              body=payment_method)
        pprint(result)
        
        
        
  • /v1/customers/:customer/payment_methods

  • Bank redirect

  • curl -X post
    https://sandboxapi.rapyd.net/v1/customers/cus_e467136cc0d5ab97ff2c3cbcda43a658/payment_methods
    -H 'access_key: your-access-key-here'
    -H 'Content-Type: application/json'
    -H 'idempotency: your-idempotency-parameter-here'
    -H 'salt: your-random-string-here'
    -H 'signature: your-calculated-signature-here'
    -H 'timestamp: your-unix-timestamp-here'
    -d '{
        "type": "fi_sepadirectdebit_bank",
        "fields": {
            "language": "es"
        },
        "metadata": {
            "merchant_defined": true
        }
    }
    '
    
  • {
        "status": {
            "error_code": "",
            "status": "SUCCESS",
            "message": "",
            "response_code": "",
            "operation_id": "d6ead88d-eafa-48e0-b048-6f4ddd0fb99f"
        },
        "data": {
            "id": "other_e1c5d34df2125607ca08978929c3dd8f",
            "type": "fi_sepadirectdebit_bank",
            "category": "bank_redirect",
            "metadata": {
                "merchant_defined": true
            },
            "image": "",
            "webhook_url": "",
            "supporting_documentation": "",
            "next_action": "user_authentication",
            "bic_swift": "ABCDEFG1234",
            "account_last4": "6283",
            "redirect_url": "https://sandboxcheckout.rapyd.net/userApproval?accessCode=",
            "language": "es"
        }
    }
  • Cash

  • curl -X post
    https://sandboxapi.rapyd.net/v1/customers/cus_e467136cc0d5ab97ff2c3cbcda43a658/payment_methods
    -H 'access_key: your-access-key-here'
    -H 'Content-Type: application/json'
    -H 'idempotency: your-idempotency-parameter-here'
    -H 'salt: your-random-string-here'
    -H 'signature: your-calculated-signature-here'
    -H 'timestamp: your-unix-timestamp-here'
    -d '{
        "type": "it_psc_cash",
        "fields": {},
        "metadata": {
            "merchant_defined": true
        }
    }
    '
    
  • {
        "status": {
            "error_code": "",
            "status": "SUCCESS",
            "message": "",
            "response_code": "",
            "operation_id": "fefb2258-da98-4311-8518-a224cdf0f783"
        },
        "data": {
            "id": "other_6b0709a10cbaa0c120d6e03de5b646c5",
            "type": "it_psc_cash",
            "category": "cash",
            "metadata": {
                "merchant_defined": true
            },
            "image": "",
            "webhook_url": "",
            "supporting_documentation": "",
            "next_action": "not_applicable"
        }
    }
  • Bank transfer

  • curl -X post
    https://sandboxapi.rapyd.net/v1/customers/cus_d3ed65d5091a8398cc3651bcedec1201/payment_methods
    -H 'access_key: your-access-key-here'
    -H 'Content-Type: application/json'
    -H 'idempotency: your-idempotency-parameter-here'
    -H 'salt: your-random-string-here'
    -H 'signature: your-calculated-signature-here'
    -H 'timestamp: your-unix-timestamp-here'
    -d '{
        "type": "us_ach_bank",
        "fields": {
            "proof_of_authorization": false,
            "first_name": "John",
            "last_name": "Doe",
            "company_name": "Acme",
            "routing_number": "345-345-op4",
            "payment_purpose": "goods",
            "account_number": "rete-34534-4t"
        },
        "metadata": {
            "merchant_defined": true
        }
    }
    '
    
  • {
        "status": {
            "error_code": "",
            "status": "SUCCESS",
            "message": "",
            "response_code": "",
            "operation_id": "a27cfdbd-3d95-475d-a381-acfb668049c1"
        },
        "data": {
            "id": "other_bc428c38988a5d5aa5a09b79f32b2b15",
            "type": "us_ach_bank",
            "category": "bank_transfer",
            "metadata": {
                "merchant_defined": true
            },
            "image": "",
            "webhook_url": "",
            "supporting_documentation": "",
            "next_action": "not_applicable",
            "last_name": "Doe",
            "first_name": "John",
            "company_name": "Acme",
            "account_number": "345-345-op4",
            "routing_number": "2345345345345345",
            "payment_purpose": "goods",
            "proof_of_authorization": false
        }
    }
  • Card

  • curl -X post
    https://sandboxapi.rapyd.net/v1/customers/cus_dade6eecffc1d3e61af83af957104b79/payment_methods
    -H 'access_key: your-access-key-here'
    -H 'Content-Type: application/json'
    -H 'idempotency: your-idempotency-parameter-here'
    -H 'salt: your-random-string-here'
    -H 'signature: your-calculated-signature-here'
    -H 'timestamp: your-unix-timestamp-here'
    -d '{
        "type": "us_debit_mastercard_card",
        "fields": {
            "number": "4111111111111111",
            "expiration_month": "12",
            "expiration_year": "25",
            "cvv": "555",
            "name": "John Doe"
        },
        "metadata": {
            "merchant_defined": true
        }
    }
    '
    
  • {
        "status": {
            "error_code": "",
            "status": "SUCCESS",
            "message": "",
            "response_code": "",
            "operation_id": "97d09603-d943-4182-bb71-cfa250b5bf3d"
        },
        "data": {
            "id": "card_d5cf1a06c0e99b5570acef624e8d984e",
            "type": "us_mastercard_card",
            "category": "card",
            "metadata": {
                "merchant_defined": true
            },
            "image": "",
            "webhook_url": "",
            "supporting_documentation": "",
            "next_action": "3d_verification",
            "name": "John Doe",
            "last4": "1111",
            "acs_check": "unchecked",
            "cvv_check": "unchecked",
            "bin_details": {
                "type": null,
                "brand": null,
                "country": null,
                "bin_number": "411111"
            },
            "expiration_year": "25",
            "expiration_month": "12",
            "fingerprint_token": "ocfp_e599f990674473ce6283b245e9ad2467",
            "redirect_url": "https://sandboxcheckout.rapyd.net/3ds-payment?token=payment_04702ec39413b0eafea1acbd533d330d"
        }
    }