Digital Wallets or e-Wallets are cards repositories and payment data for online customers. The e-wallets allows customers to use a single sign-in to make purchases on the web.

Workflow

33343334
  1. Customer fills and submits all necessary payment information to the merchant server.

  2. The merchant submits to /transactions to create the transaction.

  3. PagSeguro creates an order and returns the Transaction Code and Payment URL to the merchant.

  4. The merchant redirects the customer to PagSeguro's Payment URL.

  5. The customer accesses the Payment URL and pays the transaction through the payment method website.

  6. After the success in the payment flow, the customer will be redirected to Merchant's Success URL. If the customer cancels the process, he/she will be redirected to Merchant's Fail URL.

Creating an e-Wallet Payment

To create an e-wallet payment method, make a POST request as the example.

Request

📘

Production URL:

https://api.boacompra.com/transactions

Method: POST

🚧

Sandbox URL:

https://api.sandbox.boacompra.com/transactions

Method: POST

Example of a request using e-Wallet

{
  "transaction": {
    "reference": "REF-XXX-1539093014330",
    "project-number": 1,
    "country": "BR",
    "currency": "BRL",
    "checkout-type": "direct",
    "notification-url": "https://billing.checkout.com/processing",
    "language": "pt-BR",
    "redirect-urls": {
      "success": "https://billing.checkout.com/direct?return=1",
      "fail": "https://billing.checkout.com/direct?cancel=1"
    }
  },
  "charge": [
    {
      "amount": 100.00,
      "payment-method": {
        "type": "e-wallet",
        "sub-type": "pagseguro"
      }
    }
  ],
  "payer": {
    "name": "John Doe",
    "email": "[email protected]",
    "birth-date": "1988-12-25",
    "phone-number": "+5511991234556",
    "document": {
      "type": "CPF",
      "number": "31192071280"
    },
    "address": {
      "street": "Rua dos Bobos",
      "number": "1102",
      "complement": "AP 302",
      "district": "Vinicius de Moraes",
      "state": "PR",
      "city": "Maringá",
      "country": "BR",
      "zip-code": "87030010"
    },
    "ip": "200.221.118.80"
  },
  "shipping": {
    "cost": 0,
    "address": {
      "street": "Rua dos Bobos",
      "number": "1102",
      "complement": "AP 302",
      "district": "Vinicius de Moraes",
      "state": "PR",
      "city": "Maringá",
      "country": "BR",
      "zip-code": "87030010"
    }
  },
  "cart": [
    {
      "quantity": 1,
      "description": "Calça Jeans",
      "category": "Collectibles",
      "type": "physical",
      "unit-price": 1
    }
  ]
}

Request Parameter List

ParameterDescriptionTypeSizeMandatory
transactionSet of general transaction's informationObject-Yes
transaction.referenceMerchant transaction identifierStringUp to 64Yes
transaction.project-numberMerchant project identifier. Default value is 1Integer-No
transaction.countryCountry of the payment. Accepts only BRString2Yes
transaction.checkout-typeCheckout type of the transaction. Accepts only directString-Yes
transaction.notification-urlURL (must bind ports 80 or 443) used to send transaction status changes notifications by HTTPStringUp to 200Yes
transaction.languageLanguage used. Accepts pt-BR, en-US, es-ES, pt-PT and tr-TRString5Yes
transaction.redirect-urlsSet of URL used after finishing the payment on e-wallet's pageObject-Yes
transaction.redirect-urls.successURL used fater finishing the payment on e-wallet's pageStringUp to 200Yes
transaction.redirect-urls.failURL used when the customer cancels the process on e-wallet's pageStringUp to 200Yes
charge[]Set of payments. Currently accepting just one paymentArray1Yes
charge[].amountAmount of the transaction. Separating cents by point, with two decimal places. Amount sum must be equal to shipping.cost plus cart items valueDoubleMin of 0.01Yes
charge[].payment-method.typePayment Method type (credit-card, postpay, e-wallet or eft)String-Yes
charge[].payment-method.sub-typePayment Method sub-type. Available payment methods (see more)String-Yes
payerSet of customer's informationObject-Yes
payer.nameCustomer nameStringUp to 50Yes
payer.emailCustomer e-mailStringUp to 60Yes
payer.birth-dateCustomer birth date. ISO-8601 Pattern (YYYY-MM-DD)String-No
payer.phone-numberCustomer phone number. e.g (+5544999884455)String-No
payer.document.typeCustomer document Type. accepts: cpf and cnpjString-Yes
payer.document.numberCustomer identification document. No special characters allowed.String-Yes
payer.ipCustomer IP. accepts IPv4 or IPv6String-Yes
payer.addressCustomer address objectObject-No[1]
payer.address.streetCustomer address streetString1-160Yes
payer.address.numberCustomer address numberString1-20Yes
payer.address.complementCustomer address complementStringUp to 40No
payer.address.districtCustomer address districtString1-60Yes
payer.address.stateCustomer address state or provinceString2Yes
payer.address.cityCustomer address cityString1-60Yes
payer.address.countryCustomer address country (country iso 2)String2Yes
payer.address.zip-codeCustomer address zip codeString8Yes
shippingSet of information that will be used to deliver the items in cart (see more)Object-No[1]
shipping.costShipping cost. Separating cents by dot, with two decimal placesDoubleMin of 0.01Yes
shipping.address.streetShipping address streetString3-160Yes
shipping.address.numberShipping address numberString1-20Yes
shipping.address.complementShipping address complementString5-40No
shipping.address.districtShipping address districtString4-60Yes
shipping.address.stateShipping address state or ProvinceString2Yes
shipping.address.cityShipping address cityString3-60Yes
shipping.address.countryShipping address country (country iso 2)String2Yes
shipping.address.zip-codeShipping address zip CodeString8Yes
cart[]Set of items (at least one Item)ArrayMin of 1Yes
cart[].quantityItem quantityIntegerMin of 1Yes
cart[].descriptionItem descriptionString1-200Yes
cart[].unit-pricePrice per unit. Separating cents by dot, with two decimal placesDoubleMin of 0.01Yes
cart[].typeItem type - must be one of the following: digital, physical, service, subscriptionString-Yes
cart[].categoryItem categoryString1-64No
[1] Required when cart[].type is physical

Some considerations about the payer name:

  • Maximum length of 50 characters
  • Minimum two words
  • Each word must be separated by ONE space
  • The first and last word must have at least 2 characters long
  • Middle words can have only one character
  • Accepted characters: A to Z, uppercase and/or lowercase letters
  • Special characters accepted: éíóúãõâêôàèìòùäëïöüçñÁÉÍÓÚÃÕÂÊÔÀÈÌÒÙÄËÏÖÜÇÑ&/'.-

Some considerations about the payer email:

  • On the local-part (before the @), only alphanumeric characters and the special characters - + . _ are allowed.

Some considerations about the payer birth-date and payer phone-number:

  • Required parameters for fraud analysis to chargebacks susceptible payment types.
  • Payment type susceptible to chargebacks:
    • credit-card
    • e-wallet

Response

Example of a response using e-Wallet

{
  "transaction": {
    "code": "111115949",
    "reference": "REF-XXX-15390930143123",
    "amount": 100.00,
    "status": "PENDING",
    "currency": "BRL",
    "country": "BR",
    "payer-email": "[email protected]",
    "date-created": "2018-10-09T10:50:09.422046071-03:00",
    "payment-url": "https://gateway.boacompra.com/ewallet.php?token=B47818A1788C8DF39ECB"
  }
}

📘

Response using e-Wallet

The response body for this request is slighty different from other payment methods. The customer needs to be redirected to the e-wallet's page in order to finish the purchase.

Response Parameter List

PropertyDescriptionTypeSizeFormat
transaction.codePagSeguro´s referenceStringUp to 36e.g.: 111181153
transaction.referenceMerchant´s referenceStringUp to 64XXX-XXX-XX-XXXXXXXXXX
transaction.amountTransaction AmountNumber-e.g.: 50.0
transaction.statusCurrent status (see more)String-e.g.: PAID
transaction.currencyCurrency transactionString3e.g.: BRL
transaction.countryCountry transactionString2e.g.: BR
transaction.payer-emailPayer emailStringUp to 60e.g.: [email protected]
transaction.date-createdDate of creationString-e.g.: 2018-10-10T14:39:32.991217999-03:00
transaction.payment-urle-Wallet's page URLString-

Available Payment Methods

Payment MethodCountriesRefundsRecurringChargebacksTypeSub-type
PagSeguroBRYesNoYese-walletpagseguro
PayPalBRYesNoYese-walletpaypal
PagBankBRYesNoNoe-walletpagbank

Brazil

PagSeguro

Type: e-wallet

Sub-type:pagseguro

PagSeguro wallet gives your customers a simplified and secure checkout experience that allows them to make payments using credit cards issued in Brazil with installments. The service provide to customer make purchases adding their card of choice, using saved credit cards or available account balance.

13441344

PayPal

Type: e-wallet

Sub-type: paypal

PayPal is an e-wallet solution popular worldwide. The service allows the customer to make purchases, add their card of choice, using saved credit cards or available account balance.

800800

PagBank

Type: e-wallet

Sub-type: pagbank

PagBank e-wallet gives your customers a simplified and secure checkout experience by allowing them to make payments using their PagBank account balance through the PagBank mobile application.

There are two user experience scenarios, depending on the user device:

Scenario 1 - User experience via Mobile:

  1. The user chooses the option "Pagar com PagBank";
  2. They are redirected to a PagSeguro Payment Page with a PagBank button to complete the payment;
  3. Once the user clicks on "Pagar com PagBank", they are redirected to the PagBank application, and;
  4. After logging at the account, the user confirms the payment;
  5. If there are enough funds, the transaction is completed!
57305730

Scenario 2 - User experience via Desktop:

  1. The user chooses the option "Pagar com PagBank";
  2. They are redirected to a PagSeguro Payment Page with a QR Code and instructions to complete the payment;
  3. The user logs in to their PagBank account in the mobile application and choose the option "Pix/QR Code";
  4. The user selects "Pagar com QR Code";
  5. They scan the QR Code provided on the Desktop (also sent by email), and;
  6. Confirms the payment details;
  7. If there are enough funds, the transaction is completed!
57305730