Boleto Bancário
Boleto Bancário, ou simplement Boleto, est un mode de paiement sûr et pratique au Brésil qui permet aux payeurs d'effectuer des paiements électroniques ou en espèces pour des biens et services. Les payeurs peuvent utiliser le bordereau ou le bon Boleto émis lors du paiement pour procéder au paiement de deux manières : via leur banque en ligne, ou en imprimant le bordereau Boleto et en payant en espèces à un lieu enregistré dans tout le Brésil. Les payeurs ont la possibilité de payer plus tard et non immédiatement au moment de la validation du paiement, tandis que vous avez l'esprit tranquille en sachant que toutes les transactions Boleto Bancário sont réglementées par la Banque centrale du Brésil.
Actuellement, Mastercard Gateway ne prend en charge que les paiements Boleto Bancário en devise BRL.
Conditions préalables
Si vous souhaitez proposer Boleto Bancário comme mode de paiement à vos payeurs :
- Vous devez être inscrit auprès d'un prestataire de services de paiement pour Boleto Bancário ; par exemple, Citibank.
- Votre Your payment service provider doit activer le mode de paiement Boleto Bancário et configurer votre profil de commerçant sur Mastercard Gateway.
- Vous devez disposer de l'identifiant commerçant unique généré par votre your payment service provider, qui sera utilisé pour traiter les transactions Boleto Bancário sur le Mastercard Gateway.
Flux de paiement Boleto Bancário
Le flux d'informations générales du mode de paiement Boleto Bancário est décrit ci-dessous.
 |
Intégration et inscription auprès du prestataire de services de paiement. Le prestataire de services de paiement génère les informations d'identification suivantes : numéro de base, numéro Cosmos et numéro de portefeuille. |
 |
À l'aide des informations d'identification de l'étape 1, votre your payment service provider intègre et enregistre votre profil de commerçant sur Mastercard Gateway et génère un identifiant de commerçant unique qu'il vous indique. Vous utiliserez l'ID du commerçant pour soumettre les transactions Boleto Bancário à Mastercard Gateway. |
 |
Le payeur visite votre site Web de commerce électronique, effectue un achat et sélectionne Boleto Bancário comme mode de paiement au moment de la validation. |
 |
La passerelle de paiement reçoit la requête API pour traiter la transaction. |
 |
Votre Your payment service provider enregistre un bordereau Boleto auprès de la Chambre de compensation centrale, génère un numéro de code-barres et un numéro de série à 47 chiffres, et envoie ces détails à la passerelle de paiement. |
 |
La passerelle génère un bordereau ou un bon Boleto et vous fournit le numéro de code-barres et le numéro de série à 47 chiffres dans la réponse de l'API. De plus, une URL est fournie à partir de laquelle le bordereau Boleto peut être téléchargé ou imprimé. |
 |
Le payeur effectue un paiement en ligne en utilisant le numéro de série à 47 chiffres ou télécharge et imprime le bordereau Boleto pour payer à un lieu enregistré. Notez que les payeurs souhaitant payer à un lieu enregistré doivent avoir la possibilité de télécharger ou d'imprimer le bordereau Boleto. |
Vous pouvez télécharger le bordereau dans un délai de deux heures. Si vous souhaitez accéder au bordereau après la période de validité, contactez votre your payment service provider.
Boleto Bancário comme option de règlement dans Hosted Checkout
Si vous utilisez la page de paiement de la passerelle (Hosted Checkout), Boleto Bancário sera automatiquement proposé comme option de paiement à vos payeurs si Boleto Bancário a été configuré sur votre profil de commerçant et que les champs spécifiques à Boleto ont été soumis à la passerelle dans la demande Create Checkout Session (Créer une session de paiement).
En plus des champs standard, renseignez les champs suivants lorsque vous soumettez une demande Create Checkout Session (Créer une session de paiement) à l'aide de l'API version 58 ou supérieure :
| Champ | Requis | Description |
|---|---|---|
sourceOfFunds.provided.boletoBancario.dueDate |
Oui | Indique la date à laquelle le montant Boleto doit être payé. |
sourceOfFunds.provided.boletoBancario.daysBeforeAction |
Non | Période de grâce une fois la date dueDate passée pendant laquelle le payeur peut effectuer le paiement Boleto et avant que l'action spécifiée dans le champ actionType ne soit entreprise. |
sourceOfFunds.provided.boletoBancario.actionType |
Non | Action à entreprendre si le paiement n'est pas honoré. |
order.invoiceNumber |
Non | Numéro de facture que vous avez émis pour cette commande. Si vous n'indiquez pas de valeur, la passerelle générera le numéro et l'indiquera dans la demande. |
Lors de l'interaction Hosted Checkout, les champs suivants s'affichent si le payeur choisit de payer en utilisant le mode de paiement Boleto Bancário :
- Type de client : type de payeur ; par exemple, personne ou entreprise.
- Nom du client/Nom de l'entreprise : si le type de client = personne, il s'agit du nom du client ; si le type de client = entreprise, il s'agit du nom de l'entreprise.
- CPF/CNPJ : identifiant attribué au payeur par le gouvernement. Si le type de client = personne, il s'agit de l'identifiant Cadastro de Pessoas Fsicas (CPF) ; si le type de client = entreprise, il s'agit de l'identifiant Cadastro Nacional de Pessoas Jurdicas (CNPJ).
| URL | https://bsf.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/session/ |
| Méthode HTTP | POST |
{
"apiOperation": "CREATE_CHECKOUT_SESSION",
"interaction": {
"operation": "PURCHASE"
},
"order": {
"taxAmount": 100,
"amount": 749.99,
"currency": "BRL",
"id": "98098902948",
"invoiceNumber": "1234",
"taxRegistrationId": "12345678901",
"description": "I am using this....",
"item": [
{
"name": "Test Item 1",
"quantity": 1,
"unitPrice": "249.99"
},
{
"name": "Test Item 2",
"quantity": 1,
"unitPrice": "200"
},
{
"name": "Test Item 3",
"quantity": 1,
"unitPrice": "200"
}
]
},
"sourceOfFunds": {
"provided": {
"boletoBancario": {
"dueDate": "2020-03-02",
"daysBeforeAction": "4",
"actionType": "WRITE_OFF"
}
}
},
"billing": {
"address": {
"street": "street name",
"street2": "street name 2",
"city": "city",
"stateProvince": "MH",
"postcodeZip": "00411038"
}
},
"transaction": {
"reference": "12341234"
}
}
La réponse suivante est un exemple de transaction Boleto Bancário réussie montrant tous les détails soumis dans la demande et incluant l'URL du bordereau Boleto.
| URL | https://bsf.gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| Méthode HTTP | GET |
{
"billing":{
"address":{
"city":"city",
"postcodeZip":"00411038",
"stateProvince":"MH",
"street":"street name",
"street2":"street name 2"
}
},
"browserPayment":{
"operation":"PAY"
},
"gatewayEntryPoint":"CHECKOUT",
"merchant":"TESTMERCH01",
"order":{
"amount":749.99,
"chargeback":{
"amount":0,
"currency":"BRL"
},
"creationTime":"2020-09-03T06:26:33.932Z",
"currency":"BRL",
"customerOrderDate":"2020-09-03",
"description":"I am using this....",
"id":"order12345",
"invoiceNumber":"1234",
"item":[
{
"name":"Test Item 1",
"quantity":1,
"unitPrice":249.99
},
{
"name":"Test Item 2",
"quantity":1,
"unitPrice":200
},
{
"name":"Test Item 3",
"quantity":1,
"unitPrice":200
}
],
"itemAmount":649.99,
"lastUpdatedTime":"2020-09-03T06:26:38.056Z",
"merchantAmount":749.99,
"merchantCurrency":"BRL",
"status":"INITIATED",
"taxAmount":100,
"taxRegistrationId":"12345678901",
"totalAuthorizedAmount":0,
"totalCapturedAmount":0,
"totalRefundedAmount":0
},
"response":{
"acquirerCode":"0",
"acquirerMessage":"Data Received",
"gatewayCode":"SUBMITTED"
},
"result":"SUCCESS",
"sourceOfFunds":{
"provided":{
"boletoBancario":{
"actionType":"WRITE_OFF",
"bankAccountHolder":"TESTCUSTOMERNAME",
"customerType":"INDIVIDUAL",
"daysBeforeAction":"4",
"dueDate":"2020-03-02",
"slipUrl":"https://example.com/bpui/cb/transaction/slip/BP-0d10be5954744203eb355a1be98bb190"
}
},
"type":"BOLETO_BANCARIO"
},
"timeOfLastUpdate":"2020-09-03T06:26:38.056Z",
"timeOfRecord":"2020-09-03T06:26:33.967Z",
"transaction":{
"acquirer":{
"additionalResponseData":"{\"barcode\":\"12345678901234567890123456789012000000000001\",\"digitableLine\":\"12345678901234567890123456789012345678901234567\"}",
"id":"CITIBR_1",
"merchantId":"12335522222233331234",
"transactionId":"order12345"
},
"amount":749.99,
"currency":"BRL",
"id":"1",
"item":[
{
"name":"Test Item 1",
"quantity":1,
"unitPrice":249.99
},
{
"name":"Test Item 2",
"quantity":1,
"unitPrice":200
},
{
"name":"Test Item 3",
"quantity":1,
"unitPrice":200
}
],
"receipt":"12345678901234567890123456789012000000000001",
"reference":"000012341234",
"source":"INTERNET",
"stan":"0",
"type":"PAYMENT"
},
"version":"60"
}
Boleto Bancário comme option de paiement sur votre page de paiement
Si vous utilisez votre propre page de paiement (voir Intégration Direct Payment) et souhaitez proposer Boleto Bancário comme option de paiement à vos payeurs, vous devez renseigner les champs suivants dans la demande Pay (Payer).
Lorsque vous soumettez la demande Pay (Payer), vous devez utiliser la version 57 ou une version ultérieure de l'API.
Demande de transaction
Lorsqu'un payeur effectue un achat en utilisant Boleto Bancário comme mode de paiement, vous soumettez une demande Pay (Payer) à Mastercard Gateway et renseignez les champs comme décrit dans le tableau ci-dessous.
| Champ | Requis | Description |
|---|---|---|
sourceOfFunds.type |
Oui | Indique le mode de paiement sélectionné par le payeur. Définissez la valeur de ce champ sur BOLETO_BANCARIO. |
customer.nationalId |
Oui | Identifiant attribué au payeur par le gouvernement. Par exemple, au Brésil, il pourrait s'agir du Cadastro de Pessoas Físicas (CPF) ou du Cadastro Nacional de Pessoas Jurídicas (CNPJ). Cette valeur numérique entre 11 et 14 chiffres doit être indiquée, sinon la transaction est rejetée. |
order.referencetransaction.acquirer.transactionId |
Voir la description | Si le champ order.id que vous indiquez est conforme aux règles de validation de Boleto, il est alors utilisé comme référence de commande. Dans le cas contraire, une nouvelle référence est générée et utilisée par la passerelle.Si vous souhaitez fournir votre propre valeur de référence à Boleto, spécifiez la valeur dans le champ transaction.acquirer.transactionId. Si votre référence ne répond pas aux règles de validation de Boleto, la passerelle rejettera la transaction. Dans tous les cas, la passerelle retourne la référence utilisée dans le champ transaction.acquirer.transactionId. |
transaction.reference |
Voir la description | Le champ transaction.reference est un identifiant unique de chaque transaction Boleto Bancário généré par vous ou par votre your payment service provider. Votre Your payment service provider configurera votre profil pour l'une de ces deux méthodes au cours du processus d'intégration. Nous vous recommandons de le contacter si vous avez des questions concernant la méthode qui a été configurée pour vous.Si vous souhaitez générer l'identifiant de transaction, vous devez l'indiquer en tant que valeur dans le champ transaction.reference pour chaque transaction. Dans le cas contraire, la passerelle rejettera la transaction.Si votre your payment service provider doit générer l'identifiant de transaction, vous ne devez pas renseigner le champ, sinon la passerelle rejettera la transaction. |
sourceOfFunds.provided.boletoBancario.bankAccountHolder |
Oui | Nom du titulaire du compte bancaire pour le compte bancaire du payeur. |
sourceOfFunds.provided.boletoBancario.actionType |
Non | Action à entreprendre si le paiement n'est pas honoré. |
sourceOfFunds.provided.boletoBancario.customerType |
Non | Type de payeur ; par exemple, personne ou entreprise. La valeur par défaut est Personne. |
sourceOfFunds.provided.boletoBancario.dueDate |
Oui | Indique la date à laquelle le montant Boleto doit être payé. |
sourceOfFunds.provided.boletoBancario.daysBeforeAction |
Non | Période de grâce une fois la date dueDate passée pendant laquelle le payeur peut effectuer le paiement Boleto et avant que l'action spécifiée dans le champ actionType ne soit entreprise. |
order.invoiceNumber |
Voir la description | Numéro de facture que vous avez émis pour cette commande. Si vous n'indiquez pas de valeur, la passerelle générera le numéro et l'indiquera dans la demande. |
order.taxAmount |
Voir la description | Montant total de taxe pour la commande. Si vous n'indiquez pas de valeur, la passerelle affectera la valeur zéro et l'enverra au système en aval. Le champ order.amount sera égal au champ order.itemAmount dans la demande. |
Réponse de transaction
À moins que Mastercard Gateway ne retourne result=ERROR, la réponse inclut tous les champs de la demande et leurs valeurs qui ont été soumis dans la demande PAY (Payer). De plus, Mastercard Gateway retourne les détails décrits dans le tableau ci-dessous.
| Champ | Description |
|---|---|
response.acquirerCode |
Indique le succès ou l'échec de l'enregistrement de la transaction. Une valeur de 0 (zéro) indique un succès et une valeur de 99 indique un échec. |
response.acquirerMessage |
Message supplémentaire indiquant le succès ou l'échec de l'enregistrement de la transaction. Si l'enregistrement a réussi, ce champ contient la valeur Données reçues. Si l'enregistrement a échoué, ce champ contient la valeur Données non reçues. |
response.gatewayCode |
Indique le succès ou l'échec de l'opération. |
sourceOfFunds.provided.boletoBancario.slipUrl |
L'URL où le payeur peut accéder au coupon Boleto Bancário. |
transaction.receipt |
Lorsqu'un enregistrement de transaction réussit, la valeur de ce champ contient le nombre à 44 chiffres qui a été utilisé pour créer le code-barres sur le bordereau Boleto. Ce code-barres peut ensuite être numérisé par le vendeur si un payeur choisit de payer le bordereau Boleto à un lieu enregistré. |
transaction.acquirer.additionalResponseData |
Si l'enregistrement de la transaction échoue, ce champ contient un code d'erreur et une description au format d'une paire clé-valeur. |
La demande PAY (Payer) suivante est un exemple de transaction Boleto Bancário comprenant la date d'échéance, les jours avant qu'une action ne soit entreprise et les mesures à prendre si le bordereau Boleto n'est pas payé à la date d'échéance spécifiée.
{
"apiOperation": "PAY",
"order": {
"amount": "669.99",
"itemAmount": "649.99"
"currency": "BRL",
"taxRegistrationId": "12345678901",
"reference": "01234568",
"taxAmount": "20",
"invoiceNumber": "0001230000",
},
"transaction": {
"merchantNote": "01456789012",
"reference": "01234567",
"acquirer": {
"transactionId": "01234568"
}
},
"billing": {
"address": {
"street": "Street 123",
"street2": "Business Way",
"city": "Pune",
"stateProvince": "MH",
"postcodeZip": "12345678"
}
},
"customer": {
"nationalId": "12345678901"
},
"sourceOfFunds": {
"type": "BOLETO_BANCARIO",
"provided": {
"boletoBancario": {
"customerType": "COMPANY",
"bankAccountHolder": "FIRSTNAME LASTNAME",
"dueDate": "2021-02-17",
"daysBeforeAction": "69",
"actionType": "WRITE_OFF"
}
}
}
}
La réponse suivante est un exemple de transaction Boleto Bancário montrant tous les détails soumis dans la demande et incluant l'URL du bordereau Boleto.
{
"billing":{
"address":{
"city":"Pune",
"postcodeZip":"00411038",
"stateProvince":"MH",
"street":"YERWADA",
"street2":"Business Way"
}
},
"browserPayment":{
"operation":"PAY"
},
"gatewayEntryPoint":"WEB_SERVICES_API",
"merchant":"TESTCRMER01",
"order":{
"amount":763.99,
"chargeback":{
"amount":0,
"currency":"BRL"
},
"creationTime":"2021-02-23T07:54:25.464Z",
"currency":"BRL",
"customerOrderDate":"2021-02-23",
"discount":{
"amount":10.00
},
"id":"vp_528",
"invoiceNumber":"1230000",
"item":[
{
"name":"Korg MS-20 Mini",
"quantity":1,
"unitPrice":649.99
}
],
"itemAmount":649.99,
"lastUpdatedTime":"2021-02-23T07:54:33.993Z",
"merchantAmount":763.99,
"merchantCurrency":"BRL",
"reference":"12334",
"status":"INITIATED",
"taxAmount":124.00,
"taxRegistrationId":"12345678901",
"totalAuthorizedAmount":0,
"totalCapturedAmount":0,
"totalRefundedAmount":0
},
"response":{
"acquirerCode":"0",
"acquirerMessage":"Data Received",
"gatewayCode":"SUBMITTED"
},
"result":"SUCCESS",
"sourceOfFunds":{
"provided":{
"boletoBancario":{
"bankAccountHolder":"TEST",
"customerType":"COMPANY",
"daysBeforeAction":"4",
"dueDate":"2020-03-02",
"slipUrl":"https://dl01aspall4bv.mpgsdev.mastercard.int/bpui/cb/transaction/slip/BP-a7af97458dc12e0c57265d3bd886c4a8"
}
},
"type":"BOLETO_BANCARIO"
},
"timeOfLastUpdate":"2021-02-23T07:54:33.993Z",
"timeOfRecord":"2021-02-23T07:54:27.030Z",
"transaction":{
"acquirer":{
"additionalResponseData":"{\"barcode\":\"12345678901234567890123456789012000000000001\",\"digitableLine\":\"12345678901234567890123456789012345678901234567\"}",
"id":"CITIBR_1",
"merchantId":"12335522222233331234",
"transactionId":"12333"
},
"amount":763.99,
"currency":"BRL",
"id":"1",
"item":[
{
"name":"Korg MS-20 Mini",
"quantity":1,
"unitPrice":649.99
}
],
"merchantNote":"81",
"receipt":"12345678901234567890123456789012000000000001",
"reference":"000000000001",
"source":"INTERNET",
"stan":"0",
"type":"PAYMENT"
},
"version":"60"
}
Téléchargement ou impression du bordereau Boleto
Il est important de noter que bien que la réponse Mastercard Gateway comporte l'URL permettant d'accéder au bordereau Boleto, votre site Web de commerce électronique doit permettre à vos payeurs d'afficher, télécharger ou imprimer le bordereau Boleto.
Par exemple, cette fonctionnalité peut être un bouton sur lequel vos payeurs peuvent cliquer pour afficher et télécharger le bordereau Boleto pendant le processus de paiement.
Test de votre intégration
Vous pouvez tester votre intégration à l'aide de votre profil de commerçant de test (votre identifiant de commerçant préfixé par « TEST »). Cette rubrique fournit des détails sur le champ order.status qui peut être utilisé pour déclencher une réponse spécifique.
Avant de tester votre intégration, assurez-vous que les conditions préalables suivantes ont été remplies :
- Vous avez été intégré avec l'acquéreur.
- Votre Your payment service provider a configuré le lien d'acquéreur sur votre profil de commerçant de la passerelle en utilisant les informations suivantes que vous lui avez fournies :
- « Numéro de base », « Numéro Cosmos » et « Numéro de portefeuille ».
- Informations sur la personne qui indiquera l'identifiant unique de la transaction (transaction.reference) dans la transaction - vous ou l'acquéreur.
- Vous avez créé votre intégration en renseignant les champs obligatoires dans la demande Pay (Payer).
| RESULT | order.status |
result |
response.gatewayCode |
response.acquirerCode |
|---|---|---|---|---|
| Successful | INITIATED | SUCCESS | SUBMITTED | 0 |
| Échec | FAILED | FAILURE | UNSPECIFIED_FAILURE | 99 |
| Expiration | FAILED | FAILURE | TIMED_OUT | Sans objet |