Product Catalog
    Library
You are viewing the documentation for Chargebee API V2. If you're using the older version (V1), click here.

Payment vouchers

The Payment Voucher resource represents a voucher that has been created for a customer to initiate voucher-based payment. This resource contains relevant details such as the voucher URL, the amount of the voucher, the status of the voucher, and more. Currently, the only supported voucher-based payment source is Boleto. Boleto is a payment method in Brazil that is regulated by the Central Bank of Brazil and is considered an official form of payment. This is also a popular voucher-based payment method in Brazil.
Note: This resource can be extended in the future to support other types of payment sources for vouchers.

Sample payment voucher [ JSON ]

{ "id": "pv_1mG11S1TcNM88A9Zm", "id_at_gateway": "pi_3N0VBuK7ilSfRo7v0D66epcC", "payment_voucher_type": "boleto", "expires_at": 1682365190, "status": "active", "amount": 17800, "gateway_account_id": "gw_161my9TXG5oNYwgv", "payment_source_id": "pm_1mG11S1TcNM3LP9ZX", "gateway": "stripe", "payload": "{\"url\":\"https://payments.stripe.com/boleto/voucher/test_YWNjdF8xTHZnMFRLN2lsU2ZSbzd2LF9ObTNJN2NoejBsYldJeDI0VTVxemkwbnJaZUVTN0FH0100PvfYwtjd\",\"voucher_number\":\"01010101010101010101010101010101010101010101010\",\"expiry\":\"1682365190\"}", "url": "http://john.chargebee.com/pages/v3/__dev__w5aPBsoEK5z6kIEt2mrEIH9GWLliHXrN/view_voucher", "date": 1682365010, "updated_at": 1682365010, "resource_version": 1682365010580, "object": "payment_voucher", "currency_code": "BRL", "customer_id": "test_d23ed22ew", "linked_invoices": [{ "invoice_id": "61", "date": 1682364955, "total": 17800, "status": "payment_due" }] }

Payment voucher attributes

id
string, max chars=40
Uniquely identifies the payment voucher.
id_at_gateway
optional, string, max chars=100
The id with which this voucher is referred in gateway.
payment_voucher_type
enumerated string
Type of the payment source.
Possible values are
boletoBoleto.
expires_at
optional, timestamp(UTC) in seconds
Timestamp indicating when the Voucher will expire if left unconsumed.
status
optional, enumerated string
Current status of the payment voucher.
Possible values are
activeActive and ready to be consumed.consumedConsumed for a transaction and cannot be used again.expiredExpired before consumed and cannot be used again.failureFailed to create the voucher due to gateway rejection.
subscription_id
optional, string, max chars=50
Identifier of the subscription for which this payment voucher is made.
currency_code
string, max chars=3
The currency code (ISO 4217 format) for the voucher.
amount
optional, in cents, min=1
Amount for this payment voucher.
gateway_account_id
optional, string, max chars=50
The gateway account used for this voucher
payment_source_id
optional, string, max chars=40
Identifier of the payment source for which this payment voucher is created
gateway
enumerated string
The gateway through which this payment voucher was created.
Note: Note: Currently, stripe is the only supported gateway through which you can create the payment voucher.
Possible values are
chargebeeChargebee test gateway.chargebee_paymentsChargebee Payments gateway.stripeStripe is a payment gateway.wepayWePay is a payment gateway.
braintreeBraintree is a payment gateway.authorize_netAuthorize.net is a payment gateway.paypal_proPayPal Pro Account is a payment gateway.pinPin is a payment gateway.ewayeWAY Account is a payment gateway.eway_rapideWAY Rapid is a payment gateway.worldpayWorldPay is a payment gateway.balanced_paymentsBalanced is a payment gateway.beanstreamBambora(formerly known as Beanstream) is a payment gateway.bluepayBluePay is a payment gateway.elavonElavon Virtual Merchant is a payment solution.first_data_globalFirst Data Global Gateway Virtual Terminal Account.hdfcHDFC Account is a payment gateway.migsMasterCard Internet Gateway Service payment gateway.nmiNMI is a payment gateway.ogoneIngenico ePayments (formerly known as Ogone) is a payment gateway.paymillPAYMILL is a payment gateway.paypal_payflow_proPayPal Payflow Pro is a payment gateway.sage_paySage Pay is a payment gateway.tco2Checkout is a payment gateway.wirecardWireCard Account is a payment service provider.amazon_paymentsAmazon Payments is a payment service provider.paypal_express_checkoutPayPal Express Checkout is a payment gateway.gocardlessGoCardless is a payment service provider.adyenAdyen is a payment gateway.orbitalChase Paymentech(Orbital) is a payment gateway.moneris_usMoneris USA is a payment gateway.monerisMoneris is a payment gateway.bluesnapBlueSnap is a payment gateway.cybersourceCyberSource is a payment gateway.vantivVantiv is a payment gateway.checkout_comCheckout.com is a payment gateway.paypalPayPal Commerce is a payment gateway.ingenico_directWorldline Online Payments is a payment gateway.exactExact Payments is a payment gateway.mollieMollie is a payment gateway.quickbooksIntuit QuickBooks Payments gateway.razorpayRazorpay is a fast growing payment service provider in India working with all leading banks and support for major local payment methods including Netbanking, UPI etc.global_paymentsGlobal Payments is a payment service provider.bank_of_americaBank of America Gateway.ecentricEcentric provides a seamless payment processing service in South Africa specializing on omnichannel capabilities.metrics_globalMetrics global is a leading payment service provider providing unified payment services in the US.windcaveWindcave provides an end to end payment processing solution in ANZ and other leading global markets.ebanxEBANX is a payment gateway, enabling businesses to accept diverse local payment methods from various countries for increased market reach and conversion..not_applicableIndicates that payment gateway is not applicable for this resource.
Show all values[+]
payload
optional, string, max chars=65k
Payload from the gateway response with voucher details
error_code
optional, string, max chars=100
Error code received from the payment gateway on failure.
error_text
optional, string, max chars=65k
Error message received from the payment gateway on failure.
url
optional, string, max chars=65k
Chargebee Hosted Page url for payment voucher
date
optional, timestamp(UTC) in seconds
Indicates when this payment voucher occurred date.
resource_version
optional, long
Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.
updated_at
optional, timestamp(UTC) in seconds
Timestamp indicating when this voucher was last updated.
customer_id
string, max chars=50
The unique identifier of the customer.
linked_invoices
Show attributes[+]
optional, list of invoice_payment_voucher
Invoices related to the generated voucher
Linked invoice attributes
invoice_id
string, max chars=50
Identifier for the invoice.
txn_id
string, max chars=40
Uniquely identifies the payment voucher.
applied_at
timestamp(UTC) in seconds
Timestamp at which the transaction is applied.

Create a voucher for the customer to initiate payment

Idempotency Supported
Creates a voucher type payment source. If you create this voucher type payment source using customer details, like tax ID, you can then generate a voucher with that payment source.
Sample Request 
# creates a voucher for unpaid invoice
curl  https://{site}.chargebee.com/api/v2/payment_vouchers \
     -u {site_api_key}:\
     -d customer_id="__test__XpbTXGTSRp4Mg0Dr" \
     -d voucher_payment_source[voucher_type]="boleto" \
     -d payment_source_id="pm___dev__8asu4TZd0GfCJs" \
     -d invoice_allocations[invoice_id][0]="__demo_inv__27"
copy
# creates a voucher for unpaid invoice
curl  https://{site}.chargebee.com/api/v2/payment_vouchers \
     -u {site_api_key}:\
     -d customer_id="__test__XpbTXGTSRp4Mg0Dr" \
     -d voucher_payment_source[voucher_type]="boleto" \
     -d payment_source_id="pm___dev__8asu4TZd0GfCJs" \
     -d invoice_allocations[invoice_id][0]="__demo_inv__27"

Sample Response [ JSON ]

Show more...
{"payment_voucher": { "id": "pv_1mG11S1TcNM88A9Zm", "id_at_gateway": "pi_3N0VBuK7ilSfRo7v0D66epcC", "payment_voucher_type": "boleto", "expires_at": 1682365190, "status": "active", "amount": 17800, "gateway_account_id": "gw_161my9TXG5oNYwgv", "payment_source_id": "pm_1mG11S1TcNM3LP9ZX", "gateway": "stripe", "payload": "{\"url\":\"https://payments.stripe.com/boleto/voucher/test_YWNjdF8xTHZnMFRLN2lsU2ZSbzd2LF9ObTNJN2NoejBsYldJeDI0VTVxemkwbnJaZUVTN0FH0100PvfYwtjd\",\"voucher_number\":\"01010101010101010101010101010101010101010101010\",\"expiry\":\"1682365190\"}", "url": "http://john.chargebee.com/pages/v3/__dev__w5aPBsoEK5z6kIEt2mrEIH9GWLliHXrN/view_voucher", "date": 1682365010, "updated_at": 1682365010, "resource_version": 1682365010580, "object": "payment_voucher", "currency_code": "BRL", "customer_id": "test_d23ed22ew", "linked_invoices": [ { "invoice_id": "61", "date": 1682364955, "total": 17800, "status": "payment_due" }, {..} ] }}

URL Format POST

https://{site}.chargebee.com/api/v2/payment_vouchers

Input Parameters

customer_id
required, string, max chars=50
The unique identifier of the customer for whom you want to create the voucher.
payment_source_id
optional, string, max chars=40
The identifier of the payment source used for generating the voucher.
+
voucher_payment_source
Parameters for voucher_payment_source
pass parameters as voucher_payment_source[<param name>]
voucher_payment_source[voucher_type]
required, enumerated string
The type of voucher-based payment source.
Possible values are
boletoThe payment source is Boleto.
+
invoice_allocations
Parameters for invoice_allocations. Multiple invoice_allocations can be passed by specifying unique indices.
pass parameters as invoice_allocations[<param name>][<idx:0..n>]
invoice_allocations[invoice_id][0..n]
required, string, max chars=50
The unique identifier of the invoice. You can pass multiple invoices IDs.

Returns

payment_voucher
always returned
Resource object representing payment_voucher

Retrieve voucher data

Retrieves a voucher using the unique payment_voucher_id.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/payment_vouchers/pv_1mG11S1TcNL0SP9Vd \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/payment_vouchers/pv_1mG11S1TcNL0SP9Vd \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"payment_voucher": { "id": "pv_1mG11S1TcNL0SP9Vd", "id_at_gateway": "pi_3N0V7aK7ilSfRo7v1pfbc2NI", "payment_voucher_type": "boleto", "expires_at": 1682364922, "status": "active", "amount": 18900, "gateway_account_id": "gw_161my9TXG5oNYwgv", "payment_source_id": "pm_1mG11S1TcNKrvR9Up", "gateway": "stripe", "payload": "{\"url\":\"https://payments.stripe.com/boleto/voucher/test_YWNjdF8xTHZnMFRLN2lsU2ZSbzd2LF9ObTNFc3MzMDlsbU1qamg1Q2ROdDNzOWNYUk81bkhp0100p0cMVCz3\",\"voucher_number\":\"01010101010101010101010101010101010101010101010\",\"expiry\":\"1682364922\"}", "url": "http://john.chargebee.com/pages/v3/__dev__w5aPBsoEK5z6kIEt2mrEIH9GWLliHXrN/view_voucher", "date": 1682364742, "updated_at": 1682364742, "resource_version": 1682364742832, "object": "payment_voucher", "currency_code": "BRL", "customer_id": "test_d23ed22ew", "linked_invoices": [ { "invoice_id": "60", "date": 1682364741, "total": 18900, "status": "payment_due" }, {..} ] }}

URL Format GET

https://{site}.chargebee.com/api/v2/payment_vouchers/{payment_voucher_id}

Returns

payment_voucher
always returned
Resource object representing payment_voucher

List vouchers for an invoice

Retrieves vouchers for an invoice in reverse chronological order.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/payment_vouchers \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=1
copy
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/payment_vouchers \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=1

Sample Response [ JSON ]

Show more...
{"list": [ {"payment_voucher": { "id": "pv_1mG11S1TcNL0SP9Vd", "id_at_gateway": "pi_3N0V7aK7ilSfRo7v1pfbc2NI", "payment_voucher_type": "boleto", "expires_at": 1682364922, "status": "active", "amount": 18900, "gateway_account_id": "gw_161my9TXG5oNYwgv", "payment_source_id": "pm_1mG11S1TcNKrvR9Up", "gateway": "stripe", "payload": "{\"url\":\"https://payments.stripe.com/boleto/voucher/test_YWNjdF8xTHZnMFRLN2lsU2ZSbzd2LF9ObTNFc3MzMDlsbU1qamg1Q2ROdDNzOWNYUk81bkhp0100p0cMVCz3\",\"voucher_number\":\"01010101010101010101010101010101010101010101010\",\"expiry\":\"1682364922\"}", "url": "http://john.chargebee.com/pages/v3/__dev__w5aPBsoEK5z6kIEt2mrEIH9GWLliHXrN/view_voucher", "date": 1682364742, "updated_at": 1682364742, "resource_version": 1682364742832, "object": "payment_voucher", "linked_invoices": [ { "invoice_id": "60", "date": 1682364741, "total": 18900, "status": "payment_due" }, {..} ], "currency_code": "BRL", "customer_id": "test_d23ed22ew" }}, {..} ]}

URL Format GET

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/payment_vouchers

Input Parameters

limit
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset
optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.
sort_by[<sort-order>]
optional, string filter
Sorts based on the specified attribute.
Supported attributes : date, updated_at
Supported sort-orders : asc, desc

Example → sort_by[asc] = "date"
This will sort the result based on the 'date' attribute in ascending(earliest first) order.
Filter Params
For operator usages, see the Pagination and Filtering section.
status[<operator>]
optional, enumerated string filter
Current status of Payment Voucher. Possible values are : active, consumed, expired, failure.
Supported operators : is, is_not, in, not_in

Example → status[is_not] = "active, consumed, expired"

Returns

payment_voucher
always returned
Resource object representing payment_voucher
next_offset
optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.

List vouchers for a customer

Retrieves vouchers for a customer in reverse chronological order.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/customers/test_d23ed22ew/payment_vouchers \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=1
copy
curl  https://{site}.chargebee.com/api/v2/customers/test_d23ed22ew/payment_vouchers \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=1

Sample Response [ JSON ]

Show more...
{"list": [ {"payment_voucher": { "id": "pv_1mG11S1TcNL0SP9Vd", "id_at_gateway": "pi_3N0V7aK7ilSfRo7v1pfbc2NI", "payment_voucher_type": "boleto", "expires_at": 1682364922, "status": "active", "amount": 18900, "gateway_account_id": "gw_161my9TXG5oNYwgv", "payment_source_id": "pm_1mG11S1TcNKrvR9Up", "gateway": "stripe", "payload": "{\"url\":\"https://payments.stripe.com/boleto/voucher/test_YWNjdF8xTHZnMFRLN2lsU2ZSbzd2LF9ObTNFc3MzMDlsbU1qamg1Q2ROdDNzOWNYUk81bkhp0100p0cMVCz3\",\"voucher_number\":\"01010101010101010101010101010101010101010101010\",\"expiry\":\"1682364922\"}", "url": "http://john.chargebee.com/pages/v3/__dev__w5aPBsoEK5z6kIEt2mrEIH9GWLliHXrN/view_voucher", "date": 1682364742, "updated_at": 1682364742, "resource_version": 1682364742832, "object": "payment_voucher", "linked_invoices": [ { "invoice_id": "60", "date": 1682364741, "total": 18900, "status": "payment_due" }, {..} ], "currency_code": "BRL", "customer_id": "test_d23ed22ew" }}, {..} ]}

URL Format GET

https://{site}.chargebee.com/api/v2/customers/{customer_id}/payment_vouchers

Input Parameters

limit
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset
optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.
sort_by[<sort-order>]
optional, string filter
Sorts based on the specified attribute.
Supported attributes : date, updated_at
Supported sort-orders : asc, desc

Example → sort_by[asc] = "date"
This will sort the result based on the 'date' attribute in ascending(earliest first) order.
Filter Params
For operator usages, see the Pagination and Filtering section.
status[<operator>]
optional, enumerated string filter
Current status of Payment Voucher. Possible values are : active, consumed, expired, failure.
Supported operators : is, is_not, in, not_in

Example → status[is_not] = "active, consumed, expired"

Returns

payment_voucher
always returned
Resource object representing payment_voucher
next_offset
optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter “offset”.