- Ghid de integrare
- Caracteristici acceptate (Metode de plată)
- Boleto Bancário
Boleto Bancário
Boleto Bancário, sau pur și simplu Boleto, este o metodă de plată sigură și convenabilă în Brazilia, care permite plătitorilor să efectueze plăți electronice sau în numerar pentru bunuri și servicii. Plătitorii pot folosi borderoul sau voucherul Boleto emis la validare pentru a efectua plata folosind una din două metode: folosind serviciile bancare online sau imprimând borderoul Boleto și achitând cu numerar la o locație înregistrată din Brazilia. Plătitorii au opțiunea facilă de a plăti mai târziu, nu la validarea tranzacției, iar dvs. nu trebuie să vă faceți nicio grijă deoarece știți că toate tranzacțiile Boleto Bancário sunt reglementate de Banca Centrală a Braziliei.
În prezent, Mastercard Gateway acceptă doar plățile Boleto Bancário în moneda BRL.
Cerințe preliminare
Dacă doriți să oferiți Boleto Bancário ca metodă de plată plătitorilor dvs.:
- Trebuie să vă înregistrați la furnizorul metodei de plată pentru Boleto Bancário; de exemplu, Citibank.
- Your payment service provider trebuie să activați metoda de plată Boleto Bancário și să vă configurați profilul de comerciant pe Mastercard Gateway.
- Trebuie să aveți ID-ul unic de comerciant generat de your payment service provider, care va fi folosit pentru a procesa tranzacțiile Boleto Bancário pe Mastercard Gateway.
Procesul de plată Boleto Bancário
Fluxul de informații generale al metodei de plată Boleto Bancário este descris mai jos.
 |
Înrolarea și înregistrarea la furnizorul de metode de plată. Furnizorul metodei de plată generează următoarele acreditări. numărul de bază, numărul cosmos și numărul de portofoliu. |
 |
Folosind acreditările de la pasul 1, your payment service provider înrolează și înregistrează profilul dvs. de comerciant de pe Mastercard Gateway și generează un ID de comerciant unic pe care vi-l va pune la dispoziție. Veți utiliza ID-ul de comerciant pentru a remite tranzacții Boleto Bancário către Mastercard Gateway. |
 |
Plătitorul vizitează site-ul dvs. de comerț electronic, face o achiziție și selectează Boleto Bancário ca metodă de plată la validare. |
 |
Gateway-ul de plăți primește solicitarea API pentru a procesa tranzacția. |
 |
Your payment service provider înregistrează un Boleto la casa de compensare centrală, generează un număr tip cod de bare și un număr serial format din 47 de cifre și trimite aceste detalii către gateway-ul de plată. |
 |
Gateway-ul generează un borderou Boleto sau un voucher și vă comunică numărul tip cod de bare și numărul serial format din 47 de cifre în răspunsul API. În plus, este furnizată o adresă URL care vă permite să descărcați și să imprimați borderoul Boleto. |
 |
Plătitorul face o plată online folosind numărul serial din 47 de cifre sau descarcă și imprimă borderoul Boleto pentru a efectua plata la o locație înregistrată. Rețineți că plătitorii care doresc să plătească la o locație înregistrată trebuie să aibă posibilitatea de a descărca și imprima borderoul Boleto. |
Puteți descărca borderoul în intervalul de două ore. Dacă doriți să accesați borderoul după perioada de valabilitate, contactați your payment service provider.
Boleto Bancário ca opțiune de validare în Hosted Checkout
Dacă folosiți pagina de plată a gateway-ului (Hosted Checkout), Boleto Bancário va fi opțiunea furnizată automat ca opțiune de validare a plătitorilor dvs. dacă Boleto Bancário a fost configurat în profilul dvs. de comerciant și câmpurile specifice Boleto au fost remise către gateway în solicitarea Create Checkout Session.
Pe lângă câmpurile standard, furnizați următoarele câmpuri atunci când remiteți o solicitare Create Checkout Session folosind versiunea de API 58 sau o versiune mai recentă:
| Câmp | Obligatoriu | Descriere |
|---|---|---|
sourceOfFunds.provided.boletoBancario.dueDate |
Da | Indică data la care trebuie achitată suma din Boleto. |
sourceOfFunds.provided.boletoBancario.daysBeforeAction |
Nu | Perioada de grație după expirarea dueDate pentru efectuarea plății Boleto de către plătitor, care precede acțiunea specificată în actionType. |
sourceOfFunds.provided.boletoBancario.actionType |
Nu | Acțiunea luată în cazul în care plata nu este onorată. |
order.invoiceNumber |
Nu | Numărul facturii emise de dvs. pentru această comandă. Dacă nu furnizați o valoare, gateway-ul va genera numărul și îl va include în solicitare. |
În timpul interacțiunii Hosted Checkout, următoarele câmpuri sunt afișate dacă plătitorul alege să plătească folosind metoda de plată Boleto Bancário:
- Tip client: Tipul de plătitor; de exemplu, o persoană fizică sau juridică.
- Nume client/Nume companie: Dacă Customer Type=Individual, va fi numele clientului și, dacă Customer Type=Company, va fi numele companiei.
- CPF/CNPJ: Acesta este identificatorul plătitorului emis de o autoritate guvernamentală. Dacă Tipul de client = Persoană fizică, acesta va fi Cadastro de Pessoas Físicas (CPF), în timp ce dacă Tipul de client = Companie, acesta va fi Cadastro Nacional de Pessoas Jurídicas (CNPJ)
| URL | https://egenius.unicredit.ro/api/rest/version/72/merchant/{merchantId}/session/ |
| Metoda 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"
}
}
Acesta este un exemplu de răspuns la o tranzacție Boleto Bancário reușită, care prezintă toate detaliile remise în solicitare și include adresa URL către borderoul Boleto.
| URL | https://egenius.unicredit.ro/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| Metoda 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 ca opțiune de validare pe pagina dvs. de plată
Dacă utilizați propria dvs. pagină de plată (consultați Integrarea Direct Payment) și doriți să oferiți Boleto Bancário ca opțiune de validare pentru plătitori, trebuie să furnizați următoarele câmpuri în solicitarea Pay.
Trebuie să utilizați versiunea API 57 sau o versiune mai recentă atunci când remiteți solicitarea Pay.
Solicitare de tranzacție
Atunci când un plătitor efectuează o achiziție folosind metoda de plată Boleto Bancário, remiteți o solicitare Pay către Mastercard Gateway și furnizați câmpurile descrise în tabelul următor.
| Câmp | Obligatoriu | Descriere |
|---|---|---|
sourceOfFunds.type |
Da | Indică metoda de plată selectată de plătitor. Setați valoarea acestui câmp la BOLETO_BANCARIO. |
customer.nationalId |
Da | Identificatorul plătitorului emis de o autoritate guvernamentală. De exemplu, în Brazilia, acesta ar putea fi Cadastro de Pessoas Físicas (CPF) sau Cadastro Nacional de Pessoas Jurídicas (CNPJ). Această valoare numerică, cu o lungime de 11 până la 14 cifre, trebuie furnizată, în caz contrar, tranzacția este respinsă. |
order.referencetransaction.acquirer.transactionId |
Consultați descrierea | În cazul în care order.id furnizat este conform cu regulile de validare Boleto, atunci este utilizat pe post de referință pentru comandă. În caz contrar, se generează o referință nouă care va fi utilizată de gateway.Dacă doriți să furnizați propria valoare de referință în Boleto, specificați valoarea în câmp transaction.acquirer.transactionId. Dacă aceasta nu îndeplinește cerințele de validare Boleto, gateway-ul respinge tranzacția. În orice situație, gateway-ul va returna referința utilizată în câmpul transaction.acquirer.transactionId. |
transaction.reference |
Consultați descrierea | Câmpul transaction.reference este un identificator unic al fiecărei tranzacții Boleto Bancário, generat de dvs. sau de your payment service provider. Your payment service provider vă va configura profilul pentru una dintre aceste două metode în timpul procesului de înrolare. Vă recomandăm să îi contactați dacă aveți întrebări cu privire la metoda configurată pentru dvs.Dacă generați dvs. identificatorul tranzacției, această valoare trebuie să apară în câmpul transaction.reference pentru fiecare tranzacție. În caz contrar, gateway-ul respinge tranzacția.Dacă identificatorul tranzacției este generat de your payment service provider, nu trebuie să completați câmpul deoarece gateway-ul va respinge tranzacția. |
sourceOfFunds.provided.boletoBancario.bankAccountHolder |
Da | Numele posesorului contului bancar al plătitorului. |
sourceOfFunds.provided.boletoBancario.actionType |
Nu | Acțiunea luată în cazul în care plata nu este onorată. |
sourceOfFunds.provided.boletoBancario.customerType |
Nu | Tipul de plătitor; de exemplu, o persoană fizică sau juridică. Valoarea implicită este Individual. |
sourceOfFunds.provided.boletoBancario.dueDate |
Da | Indică data la care trebuie achitată suma din Boleto. |
sourceOfFunds.provided.boletoBancario.daysBeforeAction |
Nu | Perioada de grație după expirarea dueDate pentru efectuarea plății Boleto de către plătitor, care precede acțiunea specificată în actionType. |
order.invoiceNumber |
Consultați descrierea | Numărul facturii emise de dvs. pentru această comandă. Dacă nu furnizați o valoare, gateway-ul va genera numărul și îl va include în solicitare. |
order.taxAmount |
Consultați descrierea | Suma totală a taxelor pentru comandă. Dacă nu furnizați o valoare, gateway-ul va genera implicit o valoare zero și o va trimite către sistemul din aval. order.amount va fi egală cu order.itemAmount din solicitare. |
Răspuns de tranzacție
Dacă Mastercard Gateway nu returnează result=ERROR, răspunsul include toate câmpurile din solicitare și valorile acestora remise în solicitarea PAY. În plus, Mastercard Gateway returnează detaliile descrise în tabelul următor.
| Câmp | Descriere |
|---|---|
response.acquirerCode |
Indică succesul sau eșecul înregistrării tranzacției. O valoare 0 (zero) indică succesul, iar o valoare 99 indică eșecul. |
response.acquirerMessage |
Un mesaj suplimentar care indică succesul sau eșecul înregistrării tranzacției. Dacă înregistrarea a reușit, acest câmp conține valoarea Data Received. Dacă înregistrarea a eșuat, acest câmp conține valoarea Data Not Received. |
response.gatewayCode |
Indică succesul sau eșecul operației. |
sourceOfFunds.provided.boletoBancario.slipUrl |
Adresa URL la care plătitorul poate accesa talonul Boleto Bancário. |
transaction.receipt |
Dacă înregistrarea unei tranzacții reușește, valoarea din acest câmp conține numărul din 44 de cifre folosit pentru a crea codul de bare de pe borderoul Boleto. Acest cod de bare poate fi scanat de vânzător dacă plătitorul alege să plătească Boleto la o locație înregistrată. |
transaction.acquirer.additionalResponseData |
Dacă înregistrarea tranzacției eșuează, acest câmp conține un cod de eroare și o descriere în format de pereche cheie-valoare. |
Următorul exemplu de solicitare PAY pentru o tranzacție Boleto Bancário include data scadentă, zilele care preced luarea acțiunii și ce acțiune trebuie luată dacă Boleto nu este plătit la data scadentă specificată.
{
"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"
}
}
}
}
Următorul exemplu de răspuns al unei tranzacții Boleto Bancário arată toate detaliile care au fost trimise în solicitare și include adresa URL a fișei 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"
}
Descărcarea sau imprimarea borderoului Boleto
Chiar dacă răspunsul Mastercard Gateway include adresa URL de accesare a borderoului Boleto, este important să rețineți că site-ul dvs. de e-commerce trebuie să permită plătitorilor să vizualizeze, să descarce sau să imprime borderoul Boleto.
De exemplu, această funcționalitate poate fi un buton pe care plătitorilor pot face clic pentru a vizualiza și descărca borderoul Boleto în timpul procesului de validare.
Testarea integrării
Puteți testa integrarea folosind profilul de testare comerciant (ID-ul de comerciant cu prefixul „TEST”). Această secțiune conține detaliile privind order.status care pot fi folosite pentru a obține un răspuns specific.
Înainte de a testa integrarea, asigurați-vă că sunt îndeplinite următoarele cerințe preliminare:
- Ați fost înscris la achizitor.
- Your payment service provider a configurat linkul de achizitor în profilul dvs. de comerciant de pe gateway, folosind următoarele informații furnizate de dvs.:
- „Numărul de bază”, „Numărul de cont cosmos” și „Numărul de portofoliu”
- Informațiile privind persoana care va furniza identificatorul de tranzacție unic (transaction.reference) din tranzacție – dvs. sau achizitorul.
- Ați construit integrarea furnizând câmpurile obligatorii în solicitarea Pay.
| RESULT | order.status |
result |
response.gatewayCode |
response.acquirerCode |
|---|---|---|---|---|
| Reușit | INITIATED | SUCCESS | SUBMITTED | 0 |
| Eșuat | FAILED | FAILURE | UNSPECIFIED_FAILURE | 99 |
| Expirare solicitare | FAILED | FAILURE | TIMED_OUT | Neaplicabil |