Payment vouchers

API Version

Product Catalog

Library

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"
        }
    ]
}

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

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

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

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

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

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

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

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

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

optional, list of invoice_payment_voucher
Invoices related to the generated voucher

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

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_vouchers \
     -u {site_api_key}:\
     -d customer_id="__test__XpbTXGTSRp4Mg0Dr" \
     -d payment_source_id="pm___dev__8asu4TZd0GfCJs" \
     -d "voucher_payment_source[voucher_type]"="BOLETO" \
     -d "invoice_allocations[invoice_id][0]"="__demo_inv__27"

copy

Click to Copy

Creates a voucher for unpaid invoice

Sample Response [ JSON ]

{
    "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

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

Possible values are

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

payment_voucher

always returned
Resource object representing payment_voucher

Retrieves a voucher using the unique payment_voucher_id.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/payment_vouchers/pv_1mG11S1TcNL0SP9Vd \
     -u {site_api_key}:

copy

Click to Copy

Sample Response [ JSON ]

{
    "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}

payment_voucher

always returned
Resource object representing payment_voucher

Retrieves vouchers for an invoice in reverse chronological order.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/payment_vouchers \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=1

copy

Click to Copy

Sample Response [ JSON ]

{
    "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

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] = "active, consumed, expired"

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`.

Retrieves vouchers for a customer in reverse chronological order.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/customers/test_d23ed22ew/payment_vouchers \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=1

copy

Click to Copy

Sample Response [ JSON ]

{
    "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

limit[]

optional, integer, default=10, min=1, max=100
The number of resources to be returned.

offset[]

sort_by[<sort-order>]

Filter Params

For operator usages, see the Pagination and Filtering section.

status[<operator>]

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`.

Sample payment voucher [ JSON ]

API Index URL GET

Model Class

Payment voucher attributes

Consent Fields for Payment voucher

Custom Fields for Payment voucher

Create a voucher for the customer to initiate payment ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve voucher data ¶

Notes

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List vouchers for an invoice ¶

Notes

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List vouchers for a customer ¶

Notes

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL