Card-Issuer financing options
Last updated: Feb 27th, 8:34am
Card-issuer financing is financing through a card-issuer on their terms. You display these options to your buyers on banners or during the checkout flow.
Note: Card-issuer financing is only available in Mexico and Brazil.
Credit financing options are available to approved partners. If you are interested in becoming an approved partner, we invite you to complete the PayPal Partner form. Without this approval, calls to the PayPal Credit Financing Options APIs result in the HTTP status code of 401 Unauthorized.
Know before you code
- You must have a card-issuer financing product integrated into your branded platform.
- This integration sets up financing options using the Credit Financing Options API.
- Complete the steps in Get started to get the following sandbox account information from the Developer Dashboard:
- Your client ID
- Your personal and business sandbox accounts
- Use your client ID when adding credit options to your website. Use your sandbox accounts when testing the options.
Use cases
There are different methods you can use to display all of the card-issuer financing options to your buyers depending on the information you have.
| Option | Use case |
|---|---|
| Include card number | You have a card number and the financing country, billing country, and currency match for that card. |
| Remove card number | You don't have a card number. The financing country, billing country, and currency must match. |
| Remove billing country | You have card number and the financing country and currency match for that card, but you, as the biller, are in a different country. For example, you are in the US and you're setting up options for your buyers in Mexico. |
| Remove financing country | You have card number, the billing country and currency match for that card, and you want options for a particular financing product. |
| Remove billing and financing countries | You have card number with a matching currency, but you, as the biller, are in a different country and you want options for a particular financing product. For example, you are in the US and you're setting up particular product options for your buyers in Mexico. |
| Use reference transaction ID | You are using reference transactions or billing agreements with your buyers and you want to use those IDs as the financial instrument instead of the actual card. The financing country and its currency must match. |
| Use vaulted token | You are using a vault product to store buyer financial instrument information and you want to use a vaulted token as the financial instrument instead of the actual card. The financing country and its currency must match. |
| Use nonce | You have a nonce, a secure, one-time-use reference to payment information, and you want to use that token as the financial instrument instead of the actual card. The financing country and its currency must match. |
Include card number
To show the card issuer's supported installment options to your buyers, provide a card number that supports installments.
Sample request
API endpoint used: Calculate financing options available for a transaction
1curl -v -X POST https://api-m.sandbox.paypal.com/v1/credit/calculated-financing-options2 -H "Content-Type: application/json"3 -H "Authorization: Bearer <Access-Token>"4 -d '{5 "financing_country_code": "BR",6 "transaction_amount": {7 "value": "279.99",8 "currency_code": "BRL"9 },10 "funding_instrument": {11 "type": "PAYMENT_CARD",12 "payment_card": {13 "billing_country": "BR",14 "number": "53334189708281"15 }16 },17 "tracking_id": "EC-3GY56644419521944"18}'
Modify the code
After you copy the code in the sample request, modify the following:
- Change
Access-Tokento your access token. - Change the
numberto your card number. - Update the
financing_country_codeso that it reflects the right country:MXorBR. - Update the
currency_codeso that it reflects the right currency:MXNorBRL. - Update the
tranaction_amountvalues. - Update the
funding_instrumentvalues. - (Optional) Add a
tracking_idto help with us with debugging in the case of an error.
Step result
- A return status code of HTTP
200 OK. - A JSON response body that lists the installment options available for that card.
Sample response
1{2 "configuration_owner_account": "NHVSJJLNDCLX4",3 "financing_options": [{4 "product": "CARD_ISSUER_INSTALLMENTS",5 "credit_product_identifier": "CREDIT_CARD_INSTALLMENTS_BR",6 "option_set_id": "5f33656b-036d-4d49-bb65-f0d8d522bd22",7 "qualifying_financing_options": [{8 "credit_financing": {9 "product": "CARD_ISSUER_INSTALLMENTS",10 "credit_product_identifier": "CREDIT_CARD_INSTALLMENTS_BR",11 "apr": "0",12 "nominal_rate": "0",13 "term": 1,14 "interval": "MONTHS",15 "interval_duration": "P1M",16 "country_code": "BR",17 "credit_type": "INST",18 "enabled": true19 },20 "min_amount": {21 "currency_code": "BRL",22 "value": "0.00"23 },24 "monthly_percentage_rate": "0",25 "periodic_payment": {26 "currency_code": "BRL",27 "value": "279.99"28 },29 "monthly_payment": {30 "currency_code": "BRL",31 "value": "279.99"32 },33 "total_interest": {34 "currency_code": "BRL",35 "value": "0"36 },37 "total_cost": {38 "currency_code": "BRL",39 "value": "279.99"40 },41 "paypal_subsidy": false42 }]43 }]44}
Remove card number
To list the available options for each issuer and network that you have configured in your installment preferences, remove and do not pass the card number.
Sample request
API endpoint used: Calculate financing options available for a transaction
1curl -v -X POST https://api-m.sandbox.paypal.com/v1/credit/calculated-financing-options2 -H "Content-Type: application/json"3 -H "Authorization: Bearer <Access-Token>"4 -d '{5 "financing_country_code": "BR",6 "transaction_amount": {7 "value": "279.99",8 "currency_code": "BRL"9 },10 "funding_instrument": {11 "type": "PAYMENT_CARD",12 "payment_card": {13 "billing_country": "BR"14 }15 },16 "tracking_id": "EC-3GY56644419521943"17}'
Modify the code
After you copy the code in the sample request, modify the following:
- Change
Access-Tokento your access token. - Update the
financing_country_codeso that it reflects the right country:MXorBR. - Update the
currency_codeandbilling_countryso that they reflect the right currency:MXNorBRL. - Update the
billing_countryso that it reflects the right country:MXorBR. - (Optional) Add a
tracking_idto help with us with debugging in the case of an error.
Step result
- A return status code of HTTP
200 OK. - A JSON response body that lists the installment options for each available issuer you have configured.
Sample response
1{2 "configuration_owner_account": "NHVSJJLNDCLX4",3 "financing_options": [{4 "product": "CARD_ISSUER_INSTALLMENTS",5 "credit_product_identifier": "CREDIT_CARD_INSTALLMENTS_BR",6 "option_set_id": "bc03d665-a7bc-4b09-b26a-9fcef1711127",7 "qualifying_financing_options": [{8 "credit_financing": {9 "product": "CARD_ISSUER_INSTALLMENTS",10 "credit_product_identifier": "CREDIT_CARD_INSTALLMENTS_BR",11 "apr": "0",12 "nominal_rate": "0",13 "term": 1,14 "interval": "MONTHS",15 "interval_duration": "P1M",16 "country_code": "BR",17 "credit_type": "INST",18 "enabled": true19 },20 "min_amount": {21 "currency_code": "BRL",22 "value": "0.00"23 },24 "monthly_percentage_rate": "0",25 "periodic_payment": {26 "currency_code": "BRL",27 "value": "279.99"28 },29 "monthly_payment": {30 "currency_code": "BRL",31 "value": "279.99"32 },33 "total_interest": {34 "currency_code": "BRL",35 "value": "0"36 },37 "total_cost": {38 "currency_code": "BRL",39 "value": "279.99"40 },41 "paypal_subsidy": false42 }]43 }]44}
Remove billing country
To show the card issuer's supported installment options to your buyers without designating the billing country, provide a card number that supports installments and remove and do not pass the card billing_country. The financing options will be based on the country and currency used in financing_country_code and currency_code.
Sample request
API endpoint used: Calculate financing options available for a transaction
1curl -v -X POST https://api-m.sandbox.paypal.com/v1/credit/calculated-financing-options2 -H "Content-Type: application/json"3 -H "Authorization: Bearer <Access-Token>"4 -d '{5 "financing_country_code": "BR",6 "transaction_amount": {7 "value": "279.99",8 "currency_code": "BRL"9 },10 "funding_instrument": {11 "type": "PAYMENT_CARD",12 "payment_card": {13 "number": "53334189708281"14 }15 },16 "tracking_id": "EC-3GY56644419521944"17}'
Modify the code
After you copy the code in the sample request, modify the following:
- Change
Access-Tokento your access token. - Update the
financing_country_codeso that it reflects the right country:MXorBR. - Update the
currency_codeso that it reflects the right currency:MXNorBRL. - Update Update the card
number. - (Optional) Add a
tracking_idto help with us with debugging in the case of an error.
Step result
- A return status code of HTTP
200 OK. - A JSON response body that lists the installment options for the card issuer's supported installment options in the country and currency code sent in the request.
Sample response
1{2 "configuration_owner_account": "NHVSJJLNDCLX4",3 "financing_options": [{4 "product": "CARD_ISSUER_INSTALLMENTS",5 "credit_product_identifier": "CREDIT_CARD_INSTALLMENTS_BR",6 "option_set_id": "fc70a7a4-44ba-41e8-b768-5d28c45510fb",7 "qualifying_financing_options": [{8 "credit_financing": {9 "product": "CARD_ISSUER_INSTALLMENTS",10 "credit_product_identifier": "CREDIT_CARD_INSTALLMENTS_BR",11 "apr": "0",12 "nominal_rate": "0",13 "term": 1,14 "interval": "MONTHS",15 "interval_duration": "P1M",16 "country_code": "BR",17 "credit_type": "INST",18 "enabled": true19 },20 "min_amount": {21 "currency_code": "BRL",22 "value": "0.00"23 },24 "monthly_percentage_rate": "0",25 "periodic_payment": {26 "currency_code": "BRL",27 "value": "279.99"28 },29 "monthly_payment": {30 "currency_code": "BRL",31 "value": "279.99"32 },33 "total_interest": {34 "currency_code": "BRL",35 "value": "0"36 },37 "total_cost": {38 "currency_code": "BRL",39 "value": "279.99"40 },41 "paypal_subsidy": false42 }]43 }]44}
Remove financing country
To list the installment options available for a card without sending the financing country:
- Remove and do not pass the
financing_country_code. - Pass a product identifier:
- If the country, Mexico or Brazil, is not known at the time of the request, pass a
productwith a value ofCARD_ISSUER_INSTALLMENTS. - For Mexico, pass
credit_product_identifierswith a value ofCREDIT_CARD_INSTALLMENTS_MX. - For Brazil, pass
credit_product_identifierswith a value ofCREDIT_CARD_INSTALLMENTS_BR.
- If the country, Mexico or Brazil, is not known at the time of the request, pass a
Sample requests
API endpoint used: Calculate financing options available for a transaction
- Unknown Country
- Known Country
1curl -v -X POST https://api-m.sandbox.paypal.com/v1/credit/calculated-financing-options2 -H "Content-Type: application/json"3 -H "Authorization: Bearer <Access-Token>"4 -d '{5 "product": "CARD_ISSUER_INSTALLMENTS",6 "transaction_amount": {7 "value": "279.99",8 "currency_code": "BRL"9 },10 "funding_instrument": {11 "type": "PAYMENT_CARD",12 "payment_card": {13 "billing_country": "BR",14 "number": "53334189708281"15 }16 },17 "tracking_id": "EC-3GY56644419521944"18}'
Modify the code
After you copy the code in the sample request, modify the following:
- Change
Access-Tokento your access token. - Update the
credit_product_identifierfor known countries:CREDIT_CARD_INSTALLMENTS_MXorCREDIT_CARD_INSTALLMENTS_BR - Update the
currency_codeandbilling_countryso that they reflect the right currency:MXNorBRL. - (Optional) Add a
tracking_idto help with us with debugging in the case of an error.
Step result
- A return status code of HTTP
200 OK. - A JSON response body that lists the installment options for the card issuer's supported installment options in the country and currency code sent in the request.
Sample responses
- Unknown Country
- Known Country
1{2 "configuration_owner_account": "C2WMK6R3A27FA",3 "financing_options": [{4 "product": "CARD_ISSUER_INSTALLMENTS",5 "credit_product_identifier": "CREDIT_CARD_INSTALLMENTS_BR",6 "option_set_id": "efee32b3-be14-4ef2-bc68-0d9f0cc51613",7 "qualifying_financing_options": [{8 "credit_financing": {9 "product": "CARD_ISSUER_INSTALLMENTS",10 "credit_product_identifier": "CREDIT_CARD_INSTALLMENTS_BR",11 "apr": "0",12 "nominal_rate": "0",13 "term": 1,14 "interval": "MONTHS",15 "interval_duration": "P1M",16 "country_code": "BR",17 "credit_type": "INST",18 "enabled": true19 },20 "min_amount": {21 "currency_code": "BRL",22 "value": "0.00"23 },24 "monthly_percentage_rate": "0",25 "periodic_payment": {26 "currency_code": "BRL",27 "value": "279.99"28 },29 "monthly_payment": {30 "currency_code": "BRL",31 "value": "279.99"32 },33 "total_interest": {34 "currency_code": "BRL",35 "value": "0"36 },37 "total_cost": {38 "currency_code": "BRL",39 "value": "279.99"40 },41 "paypal_subsidy": false42 }]43 }]44}
Remove billing and financing countries
To list the installment options available for a card without sending the billing and financing country:
- Remove and do not pass the
billing_country. - Remove and do not pass the
financing_country_code. - Pass a product identifier:
- If the country, Mexico or Brazil, is not known at the time of the request, pass a
productwith a value ofCARD_ISSUER_INSTALLMENTS. - For Mexico, pass
credit_product_identifierswith a value ofCREDIT_CARD_INSTALLMENTS_MX. - For Brazil, pass
credit_product_identifierswith a value ofCREDIT_CARD_INSTALLMENTS_BR.
- If the country, Mexico or Brazil, is not known at the time of the request, pass a
Sample requests
API endpoint used: Calculate financing options available for a transaction
- Unknown Country
- Known Country
1curl -v -X POST https://api-m.sandbox.paypal.com/v1/credit/calculated-financing-options2 -H "Content-Type: application/json"3 -H "Authorization: Bearer <Access-Token>"4 -d '{5 "product": "CARD_ISSUER_INSTALLMENTS",6 "transaction_amount": {7 "value": "279.99",8 "currency_code": "BRL"9 },10 "funding_instrument": {11 "type": "PAYMENT_CARD",12 "payment_card": {13 "number": "53334189708281"14 }15 },16 "tracking_id": "EC-3GY56644419521944"17}'
Modify the code
After you copy the code in the sample request, modify the following:
- Change
Access-Tokento your access token. - For known countries, update Update the
credit_product_identifierto reflect the right country:CREDIT_CARD_INSTALLMENTS_MXorCREDIT_CARD_INSTALLMENTS_BR - Update the
currency_codeso that it reflects the right currency:MXNorBRL. - Update Update the card
number. - (Optional) Add a
tracking_idto help with us with debugging in the case of an error.
Step result
- A return status code of HTTP
200 OK. - A JSON response body that lists the installment options for the card issuer's supported installment options in the country and currency code sent in the request.
Sample responses
- Unknown Country
- Known Country
1{2 "configuration_owner_account": "C2WMK6R3A27FA",3 "financing_options": [{4 "product": "CARD_ISSUER_INSTALLMENTS",5 "credit_product_identifier": "CREDIT_CARD_INSTALLMENTS_BR",6 "option_set_id": "e3f49363-5146-4f8c-9fa9-327c39236d40",7 "qualifying_financing_options": [{8 "credit_financing": {9 "product": "CARD_ISSUER_INSTALLMENTS",10 "credit_product_identifier": "CREDIT_CARD_INSTALLMENTS_BR",11 "apr": "0",12 "nominal_rate": "0",13 "term": 1,14 "interval": "MONTHS",15 "interval_duration": "P1M",16 "country_code": "BR",17 "credit_type": "INST",18 "enabled": true19 },20 "min_amount": {21 "currency_code": "BRL",22 "value": "0.00"23 },24 "monthly_percentage_rate": "0",25 "periodic_payment": {26 "currency_code": "BRL",27 "value": "279.99"28 },29 "monthly_payment": {30 "currency_code": "BRL",31 "value": "279.99"32 },33 "total_interest": {34 "currency_code": "BRL",35 "value": "0"36 },37 "total_cost": {38 "currency_code": "BRL",39 "value": "279.99"40 },41 "paypal_subsidy": false42 }]43 }]44}
Use reference transaction ID
A reference transaction ID, such as a billing agreement ID, uses stored funding instrument information from a credit or debit card for ongoing installment payments. To use a reference transaction ID as the funding instrument, pass the ID in funding_instrument to list the financing options that are available for the stored card.
Sample request
API endpoint used: Calculate financing options available for a transaction
1curl -v -X POST https://api-m.sandbox.paypal.com/v1/credit/calculated-financing-options -H "Content-Type: application/json" -H "Authorization: Bearer <Access-Token>" -d '{2 "financing_country_code": "BR",3 "transaction_amount": {4 "value": "530.00",5 "currency_code": "BRL"6 },7 "funding_instrument": {8 "type": "BILLING_AGREEMENT",9 "billing_agreement": {10 "billing_agreement_id": "B-7SW481754W688035X"11 }12 }13}'
Modify the code
After you copy the code in the sample request, modify the following:
- Change
Access-Tokento your access token. - Update the
financing_country_codeso that it reflects the right country:MXorBR. - Update the
currency_codeso that it reflects the right currency:MXNorBRL. - Update the reference transaction ID in
billing_agreement_id. - (Optional) Add a
tracking_idto help with us with debugging in the case of an error.
Step result
- A return status code of HTTP
200 OK. - A JSON response body that lists the installment options for the card issuer's supported installment options.
Sample response
1{2 "configuration_owner_account": "C2WMK6R3A27FA",3 "financing_options": [{4 "product": "CARD_ISSUER_INSTALLMENTS",5 "credit_product_identifier": "CREDIT_CARD_INSTALLMENTS_BR",6 "option_set_id": "f8b044c2-f33b-40fa-b8eb-547ffd432019",7 "qualifying_financing_options": [{8 "credit_financing": {9 "product": "CARD_ISSUER_INSTALLMENTS",10 "credit_product_identifier": "CREDIT_CARD_INSTALLMENTS_BR",11 "apr": "0",12 "nominal_rate": "0",13 "term": 1,14 "interval": "MONTHS",15 "interval_duration": "P1M",16 "country_code": "BR",17 "credit_type": "INST",18 "enabled": true19 },20 "min_amount": {21 "currency_code": "BRL",22 "value": "0.00"23 },24 "monthly_percentage_rate": "0",25 "periodic_payment": {26 "currency_code": "BRL",27 "value": "530.00"28 },29 "monthly_payment": {30 "currency_code": "BRL",31 "value": "530.00"32 },33 "total_interest": {34 "currency_code": "BRL",35 "value": "0"36 },37 "total_cost": {38 "currency_code": "BRL",39 "value": "530.00"40 },41 "paypal_subsidy": false42 }]43 }]44}
Use vaulted token
A vaulted token ID uses stored funding instrument information from a credit or debit card or billing agreement for ongoing installment payments. To use a vaulted token ID as the funding instrument, pass the ID in funding_instrument to list the financing options that are available for the stored card.
Sample request
API endpoint used: Calculate financing options available for a transaction
1curl -v -X POST https://api-m.sandbox.paypal.com/v1/credit/calculated-financing-options -H "Content-Type: application/json" -H "Authorization: Bearer <Access-Token>" -d '{2 "financing_country_code": "BR",3 "transaction_amount": {4 "value": "530.00",5 "currency_code": "BRL"6 },7 "funding_instrument": {8 "type": "TOKEN",9 "token": {10 "type": "PAYMENT_METHOD_TOKEN",11 "payment_method_token": "6fn5twm"12 }13 }14}'
Modify the code
After you copy the code in the sample request, modify the following:
- Change
Access-Tokento your access token. - Update the
financing_country_codeso that it reflects the right country:MXorBR. - Update the
currency_codeso that it reflects the right currency:MXNorBRL. - Update the vaulted token ID in
billing_agreement_id. - (Optional) Add a
tracking_idto help with us with debugging in the case of an error.
Step result
- A return status code of HTTP
200 OK. - A JSON response body that lists the installment options for the card issuer's supported installment options.
Sample response
1{2 "configuration_owner_account": "C2WMK6R3A27FA",3 "financing_options": [{4 "product": "CARD_ISSUER_INSTALLMENTS",5 "credit_product_identifier": "CREDIT_CARD_INSTALLMENTS_BR",6 "option_set_id": "01082020-f35f-42f5-af58-369d54f807ce",7 "qualifying_financing_options": [{8 "credit_financing": {9 "product": "CARD_ISSUER_INSTALLMENTS",10 "credit_product_identifier": "CREDIT_CARD_INSTALLMENTS_BR",11 "apr": "0",12 "nominal_rate": "0",13 "term": 1,14 "interval": "MONTHS",15 "interval_duration": "P1M",16 "country_code": "BR",17 "credit_type": "INST",18 "enabled": true19 },20 "min_amount": {21 "currency_code": "BRL",22 "value": "0.00"23 },24 "monthly_percentage_rate": "0",25 "periodic_payment": {26 "currency_code": "BRL",27 "value": "530.00"28 },29 "monthly_payment": {30 "currency_code": "BRL",31 "value": "530.00"32 },33 "total_interest": {34 "currency_code": "BRL",35 "value": "0"36 },37 "total_cost": {38 "currency_code": "BRL",39 "value": "530.00"40 },41 "paypal_subsidy": false42 }]43 }]44}
Use nonce
To use a nonce, a secure, one-time-use reference to payment information, pass the nonce in funding_instrument to list the financing options that are available for the stored card.
Sample request
API endpoint used: Calculate financing options available for a transaction
1curl -v -X POST https://api-m.sandbox.paypal.com/v1/credit/calculated-financing-options2 -H "Content-Type: application/json"3 -H "Authorization: Bearer <Access-Token>"4 -d '{5 "financing_country_code": "BR",6 "transaction_amount": {7 "value": "530.00",8 "currency_code": "BRL"9 },10 "funding_instrument": {11 "type": "TOKEN",12 "token": {13 "type": "NONCE",14 "nonce": "kf3sczg"15 }16 }17}'
Modify the code
After you copy the code in the sample request, modify the following:
- Change
Access-Tokento your access token. - Update the
financing_country_codeso that it reflects the right country:MXorBR. - Update the
currency_codeso that it reflects the right currency:MXNorBRL. - Update the nonce in
nonce. - (Optional) Add a
tracking_idto help with us with debugging in the case of an error.
Step result
- A return status code of HTTP
200 OK. - A JSON response body that contains the details for qualifying and non-qualifying options:
- The financing type, term, and total cost.
- The minimum qualifying transaction amount.
- The financing code, which identifies the financing option for the payment APIs.
Sample response
1{2 "configuration_owner_account": "C2WMK6R3A27FA",3 "financing_options": [{4 "product": "CARD_ISSUER_INSTALLMENTS",5 "credit_product_identifier": "CREDIT_CARD_INSTALLMENTS_BR",6 "option_set_id": "cf8f625c-0d0a-4d60-919a-2ad5583aac4e",7 "qualifying_financing_options": [{8 "credit_financing": {9 "product": "CARD_ISSUER_INSTALLMENTS",10 "credit_product_identifier": "CREDIT_CARD_INSTALLMENTS_BR",11 "apr": "0",12 "nominal_rate": "0",13 "term": 1,14 "interval": "MONTHS",15 "interval_duration": "P1M",16 "country_code": "BR",17 "credit_type": "INST",18 "enabled": true19 },20 "min_amount": {21 "currency_code": "BRL",22 "value": "0.00"23 },24 "monthly_percentage_rate": "0",25 "periodic_payment": {26 "currency_code": "BRL",27 "value": "530.00"28 },29 "monthly_payment": {30 "currency_code": "BRL",31 "value": "530.00"32 },33 "total_interest": {34 "currency_code": "BRL",35 "value": "0"36 },37 "total_cost": {38 "currency_code": "BRL",39 "value": "530.00"40 },41 "paypal_subsidy": false42 }]43 }]44}