API Reference

Use Cases

See below all use cases covered by the Payments API and the different settlement and payment processing flows.

Authorized Payment Creation

Authorized Payment Creation, also known as payment capture, consists of processing and finalizing the payment at the time of request submission. This is the flow commonly used in various types of businesses today.

However, to effectively create a payment using this flow, the capture parameter must be sent as true.

Below is an example of a request for payment capture:

{
  "amount": 1035,
  "payment": {
    "type": "credit",
    "installments": 1,
    "capture": true,
    "softdescriptor": "PAG*TEST",
    "card": {
      "holder": "TEST HOLDER",
      "number": "5201561050025011",
      "expiry_month": "09",
      "expiry_year": "2024",
      "brand": "mastercard",
      "cvv": "123"
    }
  },
  "customer": {
    "name": "Test Buyer",
    "document": "99999999999",
    "email": "[email protected]",
    "phone": "11999999999",
    "birthdate": "1969-12-31",
    "billing_address": {
      "street": "Test Street",
      "number": "1",
      "district": "Test Neighborhood",
      "complement": "Test add-on",
      "zipcode": "99999999",
      "city": "São Paulo",
      "state": "SP",
      "country": "BRA"
    }
  }
}

Pre-authorized Payment Creation

Pre-authorized Payment Creation, also known as pre-payment capture, involves the prior processing of the payment, reservation of the customer's funds, and the subsequent partial or complete finalization of the payment after the pre-capture of the payment.

Below is a schematization of the pre-payment capture:

Schematization of Pre-Payment Capture

Schematization of Pre-Payment Capture

Generally, this payment method is used for operations that require payment guarantee or payment security, such as hotels and rental of services and products.

It is worth noting that the pre-capture will be automatically canceled if you do not complete the capture within 5 days after creating the pre-authorized payment.

Below is an example of a request for pre-payment capture:

{
  "amount": 1035,
  "payment": {
    "type": "credit",
    "installments": 1,
    "capture": false,
    "softdescriptor": "PAG*TESTE",
    "card": {
      "vault": "2beaeb98-391d-41d9-8685-61464f3c0789"
    }
  },
  "customer": {
    "name": "Test Buyer",
    "document": "99999999999",
    "email": "[email protected]",
    "phone": "11999999999",
    "birthdate": "1969-12-31",
    "billing_address": {
      "street": "Test Street",
      "number": "1",
      "district": "Test Neighborhood",
      "complement": "Test add-on",
      "zipcode": "99999999",
      "city": "São Paulo",
      "state": "SP",
      "country": "BRA"
    }
  }
}

Additionally, be mindful of the captured amount, it cannot exceed the original pre-captured amount of the payment creation.

Create Payment with Card Vault

Creating a payment with card vault involves using a card vault to perform pre-authorization or authorization of payments without sending the card details, only using its vault.

This payment creation method is useful for businesses that need the option of one-click purchase on their platform.

However, to create a payment using this method, it is necessary to perform prior tokenization of card data through the endpoint of Card Vault Creation.

Below is an example of a request for payment capture with card vault:

{
  "amount": 1035,
  "payment": {
    "type": "credit",
    "installments": 1,
    "capture": true,
    "softdescriptor": "PAG*TESTE",
    "card": {
      "vault": "2beaeb98-391d-41d9-8685-61464f3c0789"
    }
  },
  "customer": {
    "name": "Test Buyer",
    "document": "99999999999",
    "email": "[email protected]",
    "phone": "11999999999",
    "birthdate": "1969-12-31",
    "billing_address": {
      "street": "Test Street",
      "number": "1",
      "district": "Test Neighborhood",
      "complement": "Test add-on,
      "zipcode": "99999999",
      "city": "São Paulo",
      "state": "SP",
      "country": "BRA"
    }
  }
}

It is worth mentioning that it is possible to make pre-capture and capture payments using the vault.

Create Payment with Split

Creating a payment with split involves the process of altering and modifying the settlement, meaning it is not directly tied to changing the flow of payment authorization and finalization of the payment arrangement created. Therefore, you can use a split payment both in a pre-authorization and in an authorization.

This payment creation method is useful for business operations that require splitting the payment between two or more receivers. For example, when selling a product online, you can split part of the payment for the order's shipping company and part for the order's supplier, thus being able to change the settlement flow at the time of payment creation.

Below, schematization of the process flow performed:

Schematization of Payment Split

Schematization of Payment Split

It's worth mentioning that this operation cannot be performed for companies not registered on the platform, meaning you cannot specify which bank account the split will be made to.

Payment Split Considerations

On the other hand, it is necessary to raise some considerations regarding the creation of split payments:

  • Consider PRIMARY as the primary participant or originator of the payment;
  • Consider SECONDARY as secondary participants in the payment split;
  • Be aware that it is only possible to create a split with only one primary participant;
  • The primary participant cannot receive less than 1% of the payment;
  • The sum of the split values cannot differ from the net transaction amount;

Below is an example of a request for creating split payments:

{
  "amount": 1035,
  "payment": {
    "type": "credit",
    "installments": 1,
    "capture": true,
    "card": {
      "holder": "TEST HOLDER",
      "number": "5201561050025011",
      "expiryMonth": "09",
      "expiryYear": "2024",
      "brand": "mastercard",
      "cvv": "123"
    }
  },
  "customer": {
    "name": "Test Buyer",
    "document": "99999999999",
    "email": "[email protected]",
    "phone": "11999999999",
    "birthdate": "1969-12-31",
    "billingAddress": {
      "street": "Test Street",
      "number": "1",
      "district": "Test Neighborhood",
      "complement": "Test add-on",
      "zipcode": "99999999",
      "city": "São Paulo",
      "state": "SP",
      "country": "BRA"
    }
  },
  "splits": [
    {
      "recipientToken": "9b7ba208a0e54094b9c06ef479acf4b29ddc1d3a",
      "merchantType": "PRIMARY",
      "chargeFee": true,
      "type": "PERCENTAGE",
      "amountSplit": 6000
    },
    {
      "recipientToken": "4a723333747e4aa3ac10f12fa65af89e5057d651",
      "merchantType": "SECONDARY",
      "type": "PERCENTAGE",
      "chargeFee": false,
      "discountGrossAmount": false,
      "amountSplit": 4000
    },
    {
      "recipientToken": "4a723333747e4aa3ac10f12fa65af89e5057d633",
      "merchantType": "SECONDARY",
      "type": "AMOUNT",
      "chargeFee": false,
      "discountGrossAmount": false,
      "amountSplit": 200
    }
  ]
}

Delayed Split Payment Creation

Delayed split payment creation, like in standard split, involves the process of altering and modifying the settlement, meaning it is not directly tied to changing the flow of payment authorization and finalization of the payment arrangement created. Thus, you can perform both a pre-authorization and an authorization with delayed split.

However, its difference from standard split lies in the delayed moment of modifying the settlement participants of the payment, thus, unlike defining the split participants at the time of payment creation, you make this definition at a later time after the capture.

Below is a schematization of the process flow:

Schematization of Delayed Payment Split

Schematization of Delayed Payment Split

Therefore, observing the scheme, it's clear the need to perform the payment creation reques and the delayed split activation request (previously referred to as "Participants Definition").

If the establishment creates the payment informing the delayed split and by chance the definition of the participants through the Delayed Split Activation endpoint is not carried out, the payment will not be settled until the establishment that created the payments defines the participants or cancels the payment.

Below is an example of a request for creating delayed split payments:

{
  "amount": 1035,
  "payment": {
    "type": "credit",
    "installments": 1,
    "capture": true,
    "delayed_split": true,
    "softdescriptor": "PAG*TESTE",
    "card": {
      "holder": "TEST HOLDER",
      "number": "5201561050025011",
      "expiry_month": "09",
      "expiry_year": "2024",
      "brand": "mastercard",
      "cvv": "123"
    }
  },
  "customer": {
    "name": "Test Buyer",
    "document": "99999999999",
    "email": "[email protected]",
    "phone": "11999999999",
    "birthdate": "1969-12-31",
    "billing_address": {
      "street": "Test Street",
      "number": "1",
      "district": "Test Neighborhood",
      "complement": "Test add-on",
      "zipcode": "99999999",
      "city": "São Paulo",
      "state": "SP",
      "country": "BRA"
    }
  }
}

After payment creation, it is necessary to activate the payment split. Below is an example of a request:

{
  "orderId": "6183f4ac7ad8d",
  "splits": [
    {
      "recipientToken": "9b7ba208a0e54094b9c06ef479acf4b29ddc1d3a",
      "merchantType": "PRIMARY",
      "chargeFee": true,
      "type": "PERCENTAGE",
      "amountSplit": 6000
    },
    {
      "recipientToken": "4a723333747e4aa3ac10f12fa65af89e5057d651",
      "merchantType": "SECONDARY",
      "type": "PERCENTAGE",
      "chargeFee": false,
      "discountGrossAmount": false,
      "amountSplit": 4000
    },
    {
      "recipientToken": "4a723333747e4aa3ac10f12fa65af89e5057d633",
      "merchantType": "SECONDARY",
      "type": "AMOUNT",
      "chargeFee": false,
      "discountGrossAmount": false,
      "amountSplit": 200
    }
  ]
}

It is worth noting that some observations should be considered:

  • If the sum of the percentages of the delayed split participants is greater than 100%, the delayed split activation will not be carried out and will remain pending activation.
  • If the sum of the percentages of the delayed split participants is less than 100%, the delayed split activation will be carried out, and the primary participant will receive the remaining percentage left from the created split.
  • If the platform's fee for payment authorization is based on the net amount of the participant and the deduction from it results in a negative net amount to receive, the delayed split activation will not be carried out and will remain pending activation.
  • If the fee charged by the platform is not specified to be paid by any of the participants through the chargeFee parameter, it will be charged to the primary participant upon activation of the split.

In addition to considering the cases above, review the Payment Split Considerations to integrate with the split activation endpoint.