# Configuring Boleto If you're using[ DigitalRiver.js with Elements](/commerce-api/payments/payments-solutions/digitalriver.js.md), you can create a [Boleto](/commerce-api/payments/supported-payment-methods/boleto.md) payment method for your app or website in three easy steps: * [Step 1: Build a Boleto Source Request and Details object](#step-2-build-a-boleto-source-request-and-details-object) * [Step 2: Create a Boleto source using DigitalRiver.js](#step-3-create-a-boleto-source-using-digitalriver.js) * [Step 3: Use the authorized source](#step-4-use-the-authorized-source) ## Step 1: Build a Boleto Source Request and Details object Build the Boleto Source Request and Details object. The Boleto Source Request object requires the following fields: | Field | Value | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `type` | `boletoBancario` | | `sessionId` | The payment session identifier. | | `owner` | An [Owner object](/commerce-api/payments/payments-solutions/digitalriver.js/payment-methods/common-payment-objects.md#owner-object). | | `boletoBancario` | A Boleto Source Details object. | ### Boleto Source Details object Use the Boleto Source Details object code sample. ```javascript { "returnUrl": "https://example.com", "nationalId": "16235836597" } ``` The Boleto Source Details object requires the following fields: | Field | Required/Optional | Description | | ------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `returnUrl` | Required | If you choose to use the full redirect flow, this is where you will redirect your customer to after authorizing or canceling within the Boleto experience. | | `nationalId` | Required | If the shopper is an individual buyer, `nationalId` represents their CPF tax ID. If the shopper is a business shopper, `nationalId` represents their CNPJ tax ID. Use the [DigitalRiver.js Tax Identifier element](https://docs.digitalriver.com/digital-river-api/payment-integrations-1/digitalriver.js/reference/tax-identifier-element) to collect these from the shopper. | ## Step 2: Create a Boleto source using DigitalRiver.js Use the DigitalRiver.js library to create and mount elements to the HTML container. {% hint style="info" %} The `address` object must contain postal code and state/province data that [adheres to a standardized format](/commerce-api/shopper-apis/cart/creating-or-updating-a-cart/providing-address-information.md) using the `state` attribute. Note that the `state` attribute listed below corresponds to the `countrySubdivision` attribute used when providing address information. The payment session manages the correct field name on the backend. {% endhint %} ```javascript var data = { "type":"boletoBancario", "sessionId":"ea03bf6f-84ef-4993-b1e7-b7d5ecf71d1f", "owner":{ "firstName":"John", "lastName":"Doe", "email":"john.doe@gmail.com", "phoneNumber":"1555000000", "address":{ "line1":"123 Main Street", "line2":"", "city":"Mossoró", "state":"SP", "postalCode":"59625-105", "country":"BR" } }, "boletoBancario":{ nationalId: "16704641000167" } } digitalriver.createSource(data).then(function(result) { if (result.error) { //handle errors } else { var source = result.source; //send the source to back end sendToBackend(source); } }); ``` ### Boleto source response example ```javascript { "clientId":"gc", "channelId":"drdod15", "liveMode":false, "id":"42eace34-cd2c-47ff-bcde-5bedbbbffce1", "sessionId":"0f97ee7c-4c62-4ec6-b2c6-f36bd744ebdd", "clientSecret":"42eace34-cd2c-47ff-bcde-5bedbbbffce1_3606ed97-37c0-47d2-af40-79d062993ac0", "type":"boletoBancario", "reusable":false, "owner":{ "firstName":"John", "lastName":"Doe", "email":"john.doe@gmail.com", "phoneNumber":"1555000000", "address":{ "line1":"123 Main Street", "city":"Mossoró", "state":"SP", "postalCode":"59625-105", "country":"BR" } }, "amount":"100.00", "currency":"BRL", "state":"pending_funds", "creationIp":"209.87.180.27", "createdTime":"2021-10-18T18:28:36.191Z", "updatedTime":"2021-10-18T18:28:36.191Z", "flow":"receiver", "language":"en", "boletoBancario":{ "documentCode":"23790001246004987209031123456704579990000010000", "document":"https://link/to/the/payment-slip.pdf" } } ``` ## Step 3: Use the authorized source Once authorized, you can use the source by [attaching it to a cart](/commerce-api/payments/sources.md#attaching-a-payment-method-to-an-order-or-cart). {% tabs %} {% tab title="POST /v1/shoppers/me/carts/active/apply-payment-method" %} ```javascript { "paymentMethod": { "sourceId": "e7ba0595-059c-460c-bad8-2812123b9313" } } ``` {% endtab %} {% endtabs %} ## Best practices To use Boleto as a payment method: 1. [Create a cart](https://docs.digitalriver.com/commerce-api/cart/creating-or-updating-a-cart#creating-a-cart). 2. Optional. Set the locale and currency.\ `curl --location --request GET 'https://{host}/v1/shoppers/me.json?locale=pt_BR¤cy=BRL' \`\ `--header 'Content-Type: application/json'`\ `--header 'authorization: bearer ***\` 3. Optional. Set the the cart address to the BR address. 4. [Attach the tax ID to the cart](/commerce-api/shopper-apis/cart/configuring-taxes/managing-tax-identifiers.md#attaching-a-tax-identifier-to-a-cart). This action inserts the tax ID into the payment session. 5. [Create a Boleto source with a payment session ID](#step-2-create-a-boleto-source-using-digitalriver.js). Note that the tax ID is required when creating the Boleto source. The payment session ID provides the tax ID. 6. [Apply the source to the cart](https://docs.digitalriver.com/commerce-api/cart/attaching-a-payment-method-to-a-cart-or-customer#attaching-a-payment-method-to-an-order-or-cart). 7. [Submit the cart](https://docs.digitalriver.com/commerce-api/cart/submitting-a-cart). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.digitalriver.com/commerce-api/payments/payments-solutions/digitalriver.js/payment-methods/configuring-boleto.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.