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

Try in API Explorer

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

200:

STATUS

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

Try in API Explorer

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

200:

STATUS

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

Try in API Explorer

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

200:

STATUS

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

Try in API Explorer

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

200:

STATUS

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

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