Add Payment Method to Customer

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

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:

If 3DS is not required, this method triggers Payment Succeeded Webhook with a zero-amount transaction and the Card Added Successfully Webhook.
If 3DS is required, the Payment Updated webhook with a zero-amount transaction and the Card Added Successfully Webhook are sent following 3DS authentication.
In production, you cannot add a card to a customer profile for a telephone order.

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

Payment Method Failed webhook
Card Added Failure Webhook

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. You can also create a network reference ID when you create a payment. See Create Payment.

Prerequisites

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

Parameters

Request Path Parameters

- customer
- ID of the customer. String starting with cus_.

Request Header Parameters

Request Body Parameters

- address
- Describes a physical address. For details about the 'address' object, see Create Address.
- complete_payment_url
- URL where the customer is redirected after successfully completing an operation on an external page.
- error_payment_url
- URL where the customer is redirected if an error occurs during or after an operation on an external page.
- fields
- Object that contains the fields that are required for the specific payment method. Required when the token field is not used. See Get Payment Method Required Fields.
- is_default
- Indicates that the added payment method will become the customer's default payment method. If it is the only payment method of the customer then it will automatically become the default payment method even if this parameter is set to false.
  false
- metadata
- A JSON object defined by the client. See Metadata.
- network_reference_id
- Identifier for use in a recurring card payment.
- payment_method_options
- Additional fields required for the payment method. These values might vary from one use to the next, so they are not saved as part of the payment method object. Required when the type field and the fields object are used. If your organization manages 3DS authentication then it is recommended to add the 3DS parameters and currency parameter to this object. See also the related 'Card with 3DS data and currency' sample on this page.
- token
- ID of the token that represents the card. String starting with card_. Required when the type field and the fields object are not used.
- type
- Name of the payment method. Required when token is not used.

Response Parameters

- account_last4
- Last four digits of the bank account number or IBAN (International Bank Account Number).
- account_number
- Bank account number.
- acs_check
- Results of the Access Control Server (ACS) check. Possible values:
  - pass
  - fail
  - unavailable
  - unchecked
  Relevant to cards.
- address
- Describes a physical address. For details about the fields of the 'address' object, see Create Address.
- bic_swift
- BIC or SWIFT code.
- bin_details
- Bank identification details. Includes the following fields:
  bin_number
  BIN number of the bank.
  brand
  The brand of the card. For example, Visa.
  country
  Country of the bank that issued the card.
  type
  The type of the card:
  credit
  debit
  prepaid
- category
- Category of payment method. One of the following:
  bank_redirect
  bank_transfer
  card
  card_to_card
  cash
  ewallet
  rapyd_ewallet
- company_name
- Name of the customer's company.
- cvv_check
- Verification of the card’s CVV. Valid values:
  - pass
  - fail
  - unavailable
  - unchecked
- expiration_month
- Month of expiration.
  Relevant to cards.
- expiration_year
- Year of expiration.
  Relevant to cards.
- fingerprint_token
- Hash of the card number, expiration date and CVV.
  Relevant to cards.
- first_name
- Customer's first name.
- id
- ID of the payment method. String starting with card_ or other_.
- image
- A URL to the image of the icon for the type of payment method.
- is_default
- Indicates that the added payment method will become the customer's default payment method. If it is the only payment method of the customer then it will automatically become the default payment method even if this parameter is set to false.
- language
- Determines the default language of the hosted page. For a list of values, see List Supported Languages.
  When this parameter is null, the language of the user's browser is used.
  If the language of the user's browser cannot be determined, the default language is English.
- last4
- Last four digits of the card or IBAN (International Bank Account Number).
- metadata
- A JSON object defined by the client. See Metadata.
- name
- Full name of the customer.
- next_action
- Indicates the next action for completing the payment. One of the following values:
  3d_verification - The next action is 3DS authentication. Relevant only to card payments.
  pending_capture - The next action is pending the capture of the amount. Relevant only to card payments when the amount is not zero.
  pending_confirmation - The next action is pending the confirmation for the payment. Relevant to all payment methods excluding card payment.
  not_applicable - The payment has completed or the next action is not relevant.
- payment_purpose
- Purpose of the transfer, as reported by the payer's bank.
- proof_of_authorization
- Proof of authorization for the bank transfer.
- redirect_url
- URL of the hosted page that is shown to the customer.
- routing_number
- Routing number for the bank transfer.
- supporting_documentation
- Reserved.
- type
- Name of the payment method type. For example, us_mastercard_card.
  To get a list of payment methods for a country, use List Payment Methods by Country.
- webhook_url
- Reserved.

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"
    },
    "is_default": false,
    "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"
        "is_default": false
    }
}

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": {},
    "is_default": false,
    "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",
        "is_default": false
    }
}

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"
    },
    "is_default": false,
    "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,
        "is_default": 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"
    },
    "is_default": true,
    "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"                
	}
}
    "type": "us_debit_mastercard_card",
    "fields": {
        "number": "4111111111111111",
        "expiration_month": "12",
        "expiration_year": "25",
        "cvv": "555",
        "name": "John Doe"
    },
    "is_default": true,
    "metadata": {
        "merchant_defined": true
    }
}

Card with 3DS data and currency

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": "is_mastercard_card",
    "fields": {
        "name": "John Smith",
        "number": "4462030000000000",
        "expiration_month": "05",
        "expiration_year": "25",
        "cvv": "222"
    },
    "complete_payment_url": "https://www.example4567.com",
    "error_payment_url": "https://www.example4567.com",
    "payment_method_options": {
        "3d_version": "2.2.0",
        "cavv": "AddddFVmd4iZAKq7zA3u/AAAB=",
        "eci": "05",
        "xid": null,
        "ds_trans_id": "4567a4f1-faa4-419e-b39a-3cc9779398",
        "currency": "EUR"
    }
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "2fa33588-729a-496a-8646-f853ff46d523"
    },
    "data": {
        "id": "card_6c88c3931d8c76e39d24fce5521ec289",
        "type": "is_mastercard_card",
        "category": "card",
        "metadata": {},
        "image": "",
        "webhook_url": "",
        "supporting_documentation": "",
        "next_action": "not_applicable",
        "name": "John Smith",
        "last4": "0000",
        "acs_check": "unchecked",
        "cvv_check": "unchecked",
        "bin_details": {
            "type": "DEBIT",
            "brand": "VISA",
            "level": "CLASSIC",
            "issuer": "MODULR FS LIMITED",
            "country": "GB",
            "bin_number": "446203"
        },
        "expiration_year": "25",
        "expiration_month": "05",
        "fingerprint_token": "ocfp_1476e28831f830fb85356e3b61a1ed84",
        "redirect_url": "https://sandboxcheckout.rapyd.net/3ds-payment?token=payment_32b1081fa786d8a20143c697c9321238",
        "network_reference_id": 562415,
        "complete_payment_url": "https://www.example4567.com",
        "error_payment_url": "https://www.example4567.com",
        "is_default": false
    }
}

In this section:

Documentation