EasyflowEasyflowDocs

Accepting payments

Create charges with PIX, bank billet or credit card and follow them until they are paid.

On this page

Charges are created with the Create charge endpoint. A charge creates an order with its items and starts the payment with the method you choose.

Payment method method value How it works
PIX pix Created directly with the payment data of the request.
Bank billet bank-billet Created directly with the payment data of the request.
Credit card credit-card The card data is encrypted with the Easyflow JavaScript SDK before the charge is created.

Anatomy of a charge

The request body has three required fields:

Field Description
businessId Identifier of the business that receives the payment.
items Products being sold. Each item requires name, description, quantity and priceInCents.
payments How the order is paid. Each payment requires method, numberInstallments and valueInCents.

You can also send the buyer, shipping details and your own metadata. When the buyer is already registered as a customer, send only buyer.customerId instead of the other buyer details.

PIX

{
  "businessId": "YOUR_BUSINESS_ID",
  "buyer": {
    "name": "Maria Silva",
    "email": "maria@example.com",
    "document": { "type": "CPF", "number": "12345678909" }
  },
  "items": [
    {
      "name": "Premium plan",
      "description": "Monthly subscription to the premium plan",
      "quantity": 1,
      "priceInCents": 4990
    }
  ],
  "payments": [
    {
      "method": "pix",
      "numberInstallments": 1,
      "valueInCents": 4990,
      "pix": { "expirationInMinutes": 30 }
    }
  ]
}

pix.expirationInMinutes sets how long the PIX code can be paid.

Bank billet

Use the bank-billet method and, optionally, the number of days until the billet expires:

{
  "method": "bank-billet",
  "numberInstallments": 1,
  "valueInCents": 4990,
  "bankBillet": { "expirationInDays": 3 }
}

When you pay with a bank billet and identify the buyer with buyer.customerId, the customer must have an address registered. Otherwise the order is canceled.

Credit card

Card data never goes to your server in plain text. The flow has three steps:

  1. Retrieve the installment options for the amount with Get installment options.
  2. Encrypt the card data in the browser with the Easyflow JavaScript SDK.
  3. Create the charge sending the encrypted token in payments[].creditCard.token.

1. Get the installment options

curl --request GET \
  --url 'https://9iq81tsdy4.execute-api.sa-east-1.amazonaws.com/orders/installment-options?amountToBePaidInCents=4990' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'x-api-secret: YOUR_API_SECRET' \
  --header 'business-id: YOUR_BUSINESS_ID'

Each option shows the number of installments, the value of each installment, the interest and the total:

{
  "data": {
    "options": [
      { "installments": 1, "parcelValueInCents": 4990, "totalInterestInCents": 0, "totalValueInCents": 4990 },
      { "installments": 2, "parcelValueInCents": 2626, "totalInterestInCents": 262, "totalValueInCents": 5252 },
      { "installments": 3, "parcelValueInCents": 1797, "totalInterestInCents": 401, "totalValueInCents": 5391 }
    ]
  }
}

2. Encrypt the card

Load the SDK on your checkout page, configure it with your business identifier and encrypt the card data. Replace your-business-id with the identifier of your business, which contains only letters, numbers and hyphens:

<script src="https://easyflow-sdk.pages.dev/easyflow-sdk.min.js"></script>
window.easyflowSDK.configure({
  businessId: 'your-business-id',
});

const encryptedCard = await window.easyflowSDK.encrypt({
  cardNumber: '5480832801033311',
  holderName: 'JOHN DOE',
  month: '12',
  year: '2035',
  cvv: '123',
});

Send the encrypted token to your server and use it to create the charge.

3. Create the charge

{
  "method": "credit-card",
  "numberInstallments": 2,
  "valueInCents": 5252,
  "creditCard": {
    "token": "ENCRYPTED_CARD_TOKEN",
    "flag": "mastercard",
    "last4Numbers": "3311",
    "expiresAtMonth": 12,
    "expiresAtYear": 2035,
    "holderName": "JOHN DOE"
  }
}

All the creditCard fields are required for credit card payments. flag is the card brand, such as visa, mastercard, elo or american-express.

To test card payments without a real card, use the test cards of the sandbox.

Response

The response contains the identifier of the order and of each payment:

{
  "statusCode": 200,
  "data": {
    "orderId": "1a3c5e7a-9c1e-4a5c-8e9a-1c3e5a7c0029",
    "payments": ["1a3c5e7a-9c1e-4a5c-8e9a-1c3e5a7c0029"]
  }
}

Following the payment

Payments are confirmed asynchronously. To know when an order is paid:

  • Listen to the order and payment webhooks, such as order.paid. This is the recommended approach, see Webhooks.
  • Retrieve the order with Get order when you need its current state.

An order can have the status pending, paid, partially-paid, canceled, reversed, refunded or charged-back.

Splitting payments

To split the value of an item with other businesses, add commissionedParticipants to the item. Each participant has the commissionedId of the business that receives part of the funds, and the share as commissionedValueInCents or commissionedPercentage.