Overview

This guide shows you how to use the Purchase endpoint to create new subscriptions using the PIX Automático payment method. We’ll also illustrate how to work with the Ebanx sandbox simulator.

Prerequisites & limitations

Familiarity with Recurly’s API, Webhooks, and basic REST concepts
Completed the Quickstart Guide
Familiarity with Base64 value rendering
An Ebanx gateway account with Pix Automático is enabled

Definition

Creating Purchases refers to the process of generating new customer accounts alongside subscriptions in a single, consolidated call to the Recurly Purchase endpoint. This streamlines checkout experiences by bundling all required resources into one request.

Creating Purchases

Step 1: Generate a Pix Payment Request

Use a supported client library or our type payment field in your code. Our client libraries help you build out our APIs easily and process transactions faster. To specify Pix Automático, set your type enum to pix-automaticoand ensure you are passing a tax_identifier and tax_identifier_type for Brazil.

See our Pix Automático documentation for details on all required fields.

Send a request to the createpurchase endpoint on Recurly’s API, including:

Customer account data (e.g., code, name, billing info, phone number, email address, tax ID/tax type)
Subscriptions (with plan codes)
Type of payment method. In this case, pix-automatico.

Below are example calls in different languages:

purchase = {
  currency: "BRL",
  account: {
    code: "bdumonde",
    first_name: "Benjamin",
    last_name: "Du Monde",
    email: "[email protected]",
    billing_info: {
      address: {
      street1: "Avenida Nipo-brasileira 1007",
      city: "Braganca Paulista",
      region: "BR",
      postal_code: "123456",
      country: "BR",
      phone: "1234679099"
			}
    },
    type: "pix-automatico",
    tax_identifier: "brazilian-cpf-value",
    tax_identifier_type: "cpf"
  },
  subscriptions: [
    { plan_code: "coffee-monthly" }
  ]
}
invoice_collection = @client.create_purchase(body: purchase)

let purchaseReq = {
  currency: "BRL",
  account: {
    code: "bdumonde",
    first_name: "Benjamin",
    last_name: "Du Monde",
    email: "[email protected]",
    billing_info: {
			address: {
        street1: "Avenida Nipo-brasileira 1007",
        city: "Braganca Paulista",
        region: "BR",
        postal_code: "123456",
        country: "BR",
        phone: "1234679099"
			}
    },
    type: "pix-automatico",
    tax_identifier: "brazilian-cpf-value",
    tax_identifier_type: "cpf"
  },
  subscriptions: [
    { plan_code: "coffee-monthly" }
  ]
};
let invoiceCollection = await client.createPurchase(purchaseReq)

purchase = {
    "currency": "BRL",
    "account": {
        "code": "bdumonde",
        "first_name": "Benjamin",
        "last_name": "Du Monde",
        "email": "[email protected]",
      	"billing_info": {
						"address":{
              "street1": "Avenida Nipo-brasileira 1007",
              "city": "Braganca Paulista",
              "region": "BR",
              "postal_code": "123456",
              "country": "BR",
              "phone": "1234679099"
						}
        },
        "type": "pix-automatico",
        "tax_identifier": "brazilian-cpf-value",
        "tax_identifier_type": "cpf"
    },
    "subscriptions": [
        {"plan_code": "coffee-monthly"}
    ]
}
invoice_collection = client.create_purchase(purchase)

PurchaseCreate purchase = new PurchaseCreate();
purchase.setCurrency("BRL");

AccountPurchase account = new AccountPurchase();
account.setCode("bdumonde");
account.setFirstName("Benjamin");
account.setLastName("Du Monde");
account.setEmail("[email protected]");
account.setType("pix-automatico");
account.setTaxIdentifier("brazilian-cpf-value");
account.setTaxIdentifierType("cpf");

BillingInfoCreate billing = new BillingInfoCreate();
billing.setStreet1("Avenida Nipo-brasileira 1007");
billing.setCity("Braganca Paulista");
billing.setRegion("BR");
billing.setPostalCode("123456");
billing.setCountry("BR");
billing.setPhone("1234679099");

List<SubscriptionPurchase> subs = new ArrayList<>();
SubscriptionPurchase sub = new SubscriptionPurchase();
sub.setPlanCode("coffee-monthly");
subs.add(sub);
purchase.setSubscriptions(subs);

InvoiceCollection collection = client.createPurchase(purchase);

var purchaseReq = new PurchaseCreate()
{
    Currency = "BRL",
    Account = new AccountPurchase()
    {
        Code = "bdumonde",
        FirstName = "Benjamin",
        LastName = "Du Monde",
        Email = "[email protected]",
        BillingInfo = new BillingInfoCreate()
        {
            Street1 = "Avenida Nipo-brasileira 1007",
            City = "Braganca Paulista",
            Region = "BR",
            PostalCode = "123456",
            Country = "BR",
            Phone = "1234679099"
        },
        Type = "pix-automatico",
        TaxIdentifier = "brazilian-cpf-value",
        TaxIdentifierType = "cpf"
    },
    Subscriptions = new List<SubscriptionPurchase>()
    {
        new SubscriptionPurchase() { PlanCode = "coffee-monthly" }
    }
};

InvoiceCollection collection = client.CreatePurchase(purchaseReq);

Tip: Many more parameters are available. See the Create Purchase reference to learn more.

Step 2: Process the purchase response

A successful purchase returns an InvoiceCollection, which contains any charge or credit invoices generated by the request. If the purchase fails, you’ll receive an error response indicating what went wrong. Pix Automatico transactions will be in a Scheduled state, and the Invoice will be Pending.

Pix Automático uses QR Codes to allow consumers to authenticate their identity and authorize payments in their mobile apps. You will need to render the Base64 QR code value in your checkout page.

Once you have the Base64 string, you can embed it directly into your HTML using the <img> tag. The src attribute will contain the Base64 data, prefixed with data:image/png;base64.

Example:

"next_action": {
	"type": "qr_code",
	"value": "0004569821226780014br.gov.bcb.pix2556fake-pix.com.br/qr/v2/ACA4311F88661BC0D48200487EF1BCD95204000053039865802BR5910FAKEPIX Ltda6008CURITIBA62070503***12345"
},

This initial call will return different behavior in production than in sandbox.

In Production: (next_action.typeand next_action.value) represent the QR code value that you will need to render on your checkout page for the consumer to scan and continue authorizing the payment.

In Sandbox: (next_action.typeand next_action.value) will be present, but you will need to load the return_url value that represent the gateway's simulated Pix QR Code interaction with the consumer's App. You may render this in a modal for testing purposes.

invoice = invoice_collection.charge_invoice.transactions.next_action
puts "Created Invoice #{invoice}"

let invoice = invoiceCollection.chargeInvoice.Transactions.nextAction
console.log('Created Invoice:', invoice)

invoice = invoice_collection.charge_invoice.transactions.next_action
print("Created Invoice %s" % invoice)

// Create a purchase and get the transaction from the invoice
PurchaseCreate purchaseCreate = new PurchaseCreate();
// ... configure purchase ...

InvoiceCollection invoiceCollection = client.createPurchase(purchaseCreate);
Invoice invoice = invoiceCollection.getChargeInvoice();

// Access the transactions
List<Transaction> transactions = invoice.getTransactions();
Transaction transaction = transactions.get(0);

// Access transaction properties
String transactionId = transaction.getId();
String status = transaction.getStatus();
BigDecimal amount = transaction.getAmount();
String currency = transaction.getCurrency();

Invoice invoice = collection.ChargeInvoice;
Console.WriteLine($"Created Invoice with Number: {invoice.Number}");

Step 3: Verify and finish

After a successful purchase, you can confirm the details via the Recurly Admin UI or by calling Recurly’s API to list your new account, subscription, or invoice.

Please note, there will be some buffer time as the Invoice will initially be in a Processing state for a period of time. The transaction will be in a scheduled state. You will need to listen for webhooks to update your system.

Step 4: Listen for webhooks

After a successful signup, there will be several webhooks you should listen to in order to ensure you are enabling access to features on in your environment, and disabling access should a consumer decide to cancel their subscription from within their mobile banking applicaiton.

Sandbox behavior

In Step 2, Sandbox return_url behavior is outlined, but requires a bit more explanation. You may render this URL in whatever way you wish (modal, full redirect, etc.) however it is not recommended to put an immense amount of effort into it as this is not a production workflow.

To help with simulating a consumer's bank app, the gateway has provided a simulation site which can "pretend" to ferry along an enrollment signup and transaction authorization.

Step 1: Upon visiting the return URL, immediately navigate to Go to enrollment simulator.

Step 2: Approve the enrollment (for a success use case) by choosing 'Accept Agreement'. You may also deny the use case to test a consumer declining the enrollment request. This will result in a 404 page.

Step 3: Return to the original simulator URL and click Authorized = YES on page, to simulate a successful initial authorization for payment. This will result in a mostly blank page with a confusing response. Unfortunately, this is the limitation of the third party simulator.

Step 4: You're done!

Alternative Simulator Option

If you do not want to use the redirect url for Pix Enrollment and Transaction Authorization automation, you can use specific endpoints and send payloads to simulate specific behaviors.

Enrollments

Pix Recurring subscriptions require an enrollment. You can simulate enrollment confirmations, expirations, or revocations.

Endpoint: https://sandbox.ebanx.com/ws/simulator/userenrollment

{
	"integration_key": "your-test-key-here",
    "merchant_enrollment_code": "7ba7dce07d3548b0a32cfc4a18846b8b", // FETCH the subscription ID to obtain the Subscription UUID to obtain this value
	"payment_type_code": "pix-automatico", // Set to pix-automatico
    // possible actions: confirm, expire, revoke 
	"simulate_action": "confirm"
}

Transactions

Pix Recurring subscriptions require the transactions to be authorized. You can simulate transaction confirmations, cancellations, expirations, or failures.

Endpoint: https://sandbox.ebanx.com/ws/simulator/payment

{
	"integration_key": "your-test-key-here",
    "hash": "69045d239844fc4...397ddedf84bd", // Obtain via transaction.gateway_reference value on the Recurly API response.
    "simulate_action": "confirm" // possible actions: confirm, cancel, expire, fail
}

You may automate these in your code via postman or other internal means.

Next steps

Now that you can create new subscriptions, explore payment method guide to explore other use cases and limitations related to the Pix Automatico payment method.