Overview

This guide shows you how to use the Purchase endpoint to create new subscriptions using a credit card on Ebanx or WorldPay in the LATAM region. This guide is not exhaustive and focuses on providing information on required fields for the region for basic processing. For additional information on credit card processing, please see our general API documentation, or other feature docs.

Prerequisites & limitations

• Familiarity with Recurly’s API and basic REST concepts
• Familiarity with our 3DS guides:
  • 3D Secure for new cards
• Completed the Quickstart Guide
• An Ebanx or WorldPay (WPG) gateway account with credit cards and 3DS enabled in the LATAM region
• Familiarity with our tax integrations, specifically Vertex or Avalara.

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.

This is necessary for LATAM regional compliance due to the 3DS requirement for customer-initiated requests. All Subscription Signup requests from Recurly's APIs are customer initiated.

LATAM Requirements

When processing cards in LATAM, customer name, emails, addresses, tax IDs and birthdates are conditionally required. You will also need to integrate a tax service to handle compliance and region-specific taxation in certain cases. You can use Recurly's APIs or Recurly.js fields to collect specific pieces of information and send it to us for processing.

Fields to collect:

• First and Last Name
• Full billing address (at minimum)
• Date of Birth
• A valid email address
• A valid Tax ID (and type, conditionally)

Creating Purchases / Subscriptions

Step 1: Generate a Card Payment Request + Subscription

Use a supported client library, Recurly.js and/or a V3 Recurly API implementation. Our client libraries help you build out our APIs easily and process transactions faster. Cards for LATAM customers may conditionally require 3DS handling via Recurly.js, so ensure, no matter how you pass in card data, that you are handling 3DS Action and 3Ds Action Result tokens where necessary. See our 3DS documentation for details.

Send a request to the create /purchase endpoint on Recurly’s API, including:

• Customer account data (e.g., code, name, billing info, phone number, email address, date of birth, tax ID, and card or Recurly.js token-id containing the card number)
• Subscriptions (with plan codes)

Please Note: You can use the /subscriptions endpoint as well, but make sure you're passing in all the same required data.

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

{
    "currency": "BRL",
    "account": {
        "code":"account-code",
        "email":"[email protected]",
        "billing_info": {
            "first_name":"John",
            "last_name":"Doe",
            "address":{
                "street1":"Carrera 7 No. 123-45",
                "city":"Bogotá",
                "postal_code":"110111",
                "region":"Bogotá",
                "country":"BR"
            },
            "number": "4111111111111111",
            "month": "03",
            "year": "2030",
            "cvv": "123",
            "tax_identifier_type":"tax-id-type",
            "tax_identifier":"tax-identifier-value",
            "date_of_birth":"YYYY-MM-DD"
        }
    },
    "gateway_code":"yp92b88r7seb"
}

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. Card transactions for LATAM customers will be in a terminal (final) state (either approved or declined), and the Invoice, where applicable will be approved or declined.

In this step, you will handle the 3DS flow using Recurly.js as documented in the below two guides if your transaction uses 3DS:

• 3D Secure for new cards

Please reference 3DS flows for Recurly.js and return to this page.

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.

Step 4: Listen for webhooks

After a successful signup, there will be webhooks you should listen to in order to ensure you are enabling access to features on in your environment.

Next steps

Now that you can create new subscriptions, explore other LATAM payment method guide to explore other use cases.