- Ghid de integrare
- Caracteristici acceptate (Metode de plată)
- Plățile cu posesorul cardului prezent
Posesor de card prezent
Plățile cu posesorul cardului prezent (Cardholder Present – CHP) se referă la tranzacțiile efectuate cu un terminal Punct de plată (POS). Terminalul poate citi datele de pe card prin:
- introducerea unui card EMV
- NFC (Near Field Communication), în cazul cardurilor contactless
- trecerea prin aparat a unui card cu bandă magnetică
- introducerea numărului cardului
Compatibilitatea cu toate metodele de mai sus există în webServices Integration începând cu versiunea 40.
O plată CHP este inițiată de un terminal și trimisă către gateway sub forma unei tranzacții Verify, Authorize, Capture, Pay sau Refund. De exemplu, tranzacțiile autorizate offline de către cipul cardului vor fi trimise exclusiv ca tranzacții de decontare Capture, în timp ce tranzacțiile care necesită autorizația emitentului vor utiliza o tranzacție Authorize online și apoi o tranzacție Capture.
Tranzacțiile CHP pot funcționa împreună cu numeroase alte funcții de pe gateway. Puteți să:
- creați simboluri pentru carduri,
- rambursați sume folosind aceeași integrare utilizată pentru tranzacțiile magazinului dvs. sau prin intermediul IU,
- unificați raportarea pentru comerțul electronic și CHP.
Cerințe preliminare
Your payment service provider și achizitorul dvs. trebuie activeze tranzacțiile cu posesorul cardului prezent.
Câmpuri comune utilizate pentru tranzacțiile CHP
Următoarele câmpuri din API sunt aplicabile tuturor integrărilor cu posesorul cardului prezent de pe gateway.
transaction.source=CARD_PRESENT: Dacă nu completați acest câmp, va fi utilizată sursa implicită a tranzacției, configurată în legătura dvs. achizitor de către your payment service provider. [REST][NVP]- număr card: Introducerea numărului de card este obligatorie, însă, în funcție de modul de citire a cardului (introducerea numărului, bandă magnetică sau cip EMV), îl puteți introduce:
sourceOfFunds.provided.card.numberpentru tranzacțiile cu introducere a numărului de card.sourceOfFunds.provided.card.track1și/sausourceOfFunds.provided.card.track2pentru tranzacțiile cu bandă magnetică sau
echivalentele cu etichetă EMV ale acestora, respectiv eticheta 56 și eticheta 57,m furnizate însourceOfFunds.provided.card.emvRequestpentru tranzacțiile contactless în care datele cardului au formatul de bandă magnetică.- Eticheta 5A din
sourceOfFunds.provided.card.emvRequestpentru tranzacții EMV (cu contact/contactless) când datele cardului au formatul EMV. sourceOfFunds.provided.card.p2pe.payloadpentru tranzacții P2PE (Point-to-Point Encryption) când datele cardului au formatul criptat DUKPT.
- identificatorul terminalului: Introducerea identificatorului terminalului este obligatorie, însă, în funcție de modul de citire a cardului (introducerea numărului, bandă magnetică sau cip EMV), îl puteți introduce:
posTerminal.lanepentru tranzacțiile cu introducerea numărului cardului și tranzacțiile pe bază de bandă magnetică.- Eticheta 9F1C din
sourceOfFunds.provided.card.emvRequestpentru tranzacții EMV (cu contact/contactless) când datele cardului au formatul EMV.
Asigurați-vă că valorile următoarelor câmpuri pentru terminalul POS sunt setate corect, în funcție de modul în care terminalul a generat datele cardului pentru tranzacție. Dacă datele pentru aceste câmpuri sunt disponibile, furnizați-le întotdeauna. Gateway-ul va transmite datele conform cerințelor achizitorului. Dacă achizitorul solicită un câmp care nu este prezent, tranzacția va eșua.
posTerminal.addressposTerminal.attended: Dacă nu completați acest câmp, gateway-ul va utilizaUNKNOWN_OR_UNSPECIFIEDca valoare implicităposTerminal.authorizationMethodposTerminal.cardHolderActivated: Dacă nu completați acest câmp, gateway-ul va utilizaNOT_CARDHOLDER_ACTIVATEDca valoare implicităposTerminal.inputCapability: Acest câmp este obligatoriu pentru tranzacțiile EMV.posTerminal.location: Acest câmp este obligatoriu pentru tranzacțiile EMV.posTerminal.panEntryModeposTerminal.pinEntryCapabilityposTerminal.onlineReasonCode: Acest câmp este obligatoriu pentru tranzacțiile cu cip și cele de rezervă (inclusiv stornările) în cazul tuturor tranzacțiilor online.posTerminal.serialNumberposTerminal.mobile.cardInputDevice: Acest câmp se aplică dispozitivelor POS mobile (mPOS) capabile de a accepta atingerea ecranului sau o tastatură fizică pentru introducerea codului PIN. Codurile PIN software ar trebui utilizate doar pentru dispozitive care nu au tastatură hardware pentru introducerea codurilor PIN. Pentru cerințele de integrare mPOS, consultați Integrarea pentru utilizarea mPOS.order.gratuityAmount: Completați acest câmp dacă plata include o gratuitate.
[REST][NVP]order.cashbackAmount: Completați acest câmp dacă plata include o sumă restituită.
[REST][NVP]order.cashAdvance: Completați acest câmp dacă plata include un avans în numerar.
[REST][NVP]
Referință API Terminal POS [REST][NVP]
Procesați o tranzacție pe bază de bandă magnetică
Dacă datele pistei cardului au fost citite de pe banda magnetică a cardului,
- Furnizați datele pistei 1 în
sourceOfFunds.provided.card.track1sau datele pistei 2 în câmpulsourceOfFunds.provided.card.track2. Dacă la terminal sunt disponibile atât pista 1, cât și pista 2, atunci furnizați-le pe ambele în solicitarea de tranzacție. - Completați câmpurile obligatorii.
- Completați câmpurile opționale, dacă este necesar.
sourceOfFunds.provided.card.track1 [REST][NVP]
sourceOfFunds.provided.card.track2 [REST][NVP]
Iată un exemplu de tranzacție de autorizare online pe baza datelor benzii magnetice.
| URL | https://api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| Metoda HTTP | PUT |
{
"apiOperation": "AUTHORIZE",
"order": {
"amount": 80,
"currency": "AUD"
},
"transaction": {
"source": "CARD_PRESENT",
"frequency": "SINGLE"
},
"sourceOfFunds": {
"type": "CARD",
"provided": {
"card": {
"number": "5457210089020012",
"sequenceNumber": "015",
"expiry": {
"year": "39",
"month": "01"
},
"track2": ";5123456789012346=17051019681143384001?",
"track1": "%B5123456789012346^MR JOHN R SMITH ^17051019681143300001 840 ?;"
}
}
},
"posTerminal": {
"lane": "AdamLane",
"panEntryMode": "SWIPE",
"pinEntryCapability": "PIN_NOT_SUPPORTED",
"attended": "UNATTENDED",
"cardholderActivated": "SELF_SERVICE_TERMINAL",
"inputCapability": "MAGNETIC_STRIPE",
"location": "MERCHANT_TERMINAL_OFF_PREMISES"
}
}
{
"authorizationResponse": {
"posData": "1605S0100130",
"transactionIdentifier": "AmexTidTest"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TESTSMOKE-RETAIL",
"order": {
"amount": 80,
"creationTime": "2017-05-31T07:49:46.351Z",
"currency": "AUD",
"id": "sa-e229682a-2163-47cf-b080-fb60dd148192",
"status": "AUTHORIZED",
"totalAuthorizedAmount": 80,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0
},
"posTerminal": {
"attended": "UNATTENDED",
"cardholderActivated": "SELF_SERVICE_TERMINAL",
"inputCapability": "MAGNETIC_STRIPE",
"lane": "AdamLane",
"location": "MERCHANT_TERMINAL_OFF_PREMISES",
"panEntryMode": "SWIPE",
"pinEntryCapability": "PIN_NOT_SUPPORTED"
},
"response": {
"acquirerCode": "00",
"gatewayCode": "APPROVED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "DEBIT",
"issuer": "CAPITAL ONE BANK (CANADA BRANCH)",
"number": "545721xxxxxx0012",
"scheme": "MASTERCARD",
"sequenceNumber": "015",
"trackDataProvided": true
}
},
"type": "CARD"
},
"timeOfRecord": "2017-05-31T07:49:46.351Z",
"transaction": {
"acquirer": {
"batch": 1,
"id": "SYSTEST_ACQ1",
"merchantId": "12345678"
},
"amount": 80,
"authorizationCode": "000001",
"currency": "AUD",
"frequency": "SINGLE",
"id": "1",
"receipt": "1705313",
"source": "CARD_PRESENT",
"terminal": "0006",
"type": "AUTHORIZATION"
},
"version": "43"
}
Procesarea unei tranzacții introduse
Dacă numărul cardului a fost introdus manual pe tastatura terminalului,
- Furnizați numărul introdus al cardului în câmpul
sourceOfFunds.provided.card.numberdin solicitare. - Completați câmpurile obligatorii.
- Completați câmpurile opționale, dacă este necesar.
sourceOfFunds.provided.card.number[REST][NVP]
Iată un exemplu de tranzacție de autorizare online pe baza unui număr de card introdus manual.
| URL | https://api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| Metoda HTTP | PUT |
{
"posTerminal": {
"serialNumber": "13130PP800781435",
"cardholderActivated": "NOT_CARDHOLDER_ACTIVATED",
"lane": "S2_Lane",
"panEntryMode": "KEYED",
"pinEntryCapability": "UNKNOWN",
"attended": "ATTENDED",
"inputCapability": "KEY_ENTRY",
"location": "MERCHANT_TERMINAL_ON_PREMISES"
},
"apiOperation": "AUTHORIZE",
"sourceOfFunds": {
"type": "CARD",
"provided": {
"card": {
"number": "5457210089020012",
"sequenceNumber": "000",
"expiry": {
"year": "39",
"month": "01"
}
}
}
},
"order": {
"amount": "100.00",
"currency": "EUR"
},
"transaction": {
"source": "CARD_PRESENT",
"frequency": "SINGLE"
}
}
{
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TESTSMOKE-RETAIL",
"order": {
"amount": 100,
"creationTime": "2017-05-31T08:59:47.194Z",
"currency": "EUR",
"id": "sa-529e784a-e11d-474d-8012-c0790531bb0f",
"status": "AUTHORIZED",
"totalAuthorizedAmount": 100,
"totalCapturedAmount": 0,
"totalRefundedAmount": 0
},
"posTerminal": {
"attended": "ATTENDED",
"cardholderActivated": "NOT_CARDHOLDER_ACTIVATED",
"inputCapability": "KEY_ENTRY",
"lane": "S2_Lane",
"location": "MERCHANT_TERMINAL_ON_PREMISES",
"panEntryMode": "KEYED",
"pinEntryCapability": "UNKNOWN",
"serialNumber": "13130PP800781435"
},
"response": {
"gatewayCode": "APPROVED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "DEBIT",
"issuer": "CAPITAL ONE BANK (CANADA BRANCH)",
"number": "545721xxxxxx0012",
"scheme": "MASTERCARD",
"sequenceNumber": "000"
}
},
"type": "CARD"
},
"timeOfRecord": "2017-05-31T08:59:47.194Z",
"transaction": {
"acquirer": {
"batch": 1,
"id": "FOOBANK",
"merchantId": "11223344"
},
"amount": 100,
"authorizationCode": "471223",
"currency": "EUR",
"frequency": "SINGLE",
"id": "1",
"receipt": "170531475",
"source": "CARD_PRESENT",
"terminal": "0001",
"type": "AUTHORIZATION"
},
"version": "43"
}
Procesarea unei tranzacții Point-to-Point Encryption (P2PE)
P2PE este un standard stabilit de PCI Security Standards Council. În cazul P2PE, datele sensibile ale cardului sunt criptate pe terminal imediat ce sunt citite datele de pe card. Acest lucru asigură un nivel maxim de securitate pentru tranzacțiile cu posesorul cardului prezent și vă reduce obligațiile de conformitate cu PCI, deoarece nu este necesar să procesați date sensibile.
Pentru a procesa o tranzacție P2PE:
- Furnizați datele DUKPT P2PE de la terminal în următoarele câmpuri:
sourceOfFunds.provided.card.p2pe.keySerialNumber: Trebuie să introduceți numărul de serie al cheii DUKPT, furnizat de terminal.sourceOfFunds.provided.card.p2pe.payload: Dacă acest câmp este completat,sourceOfFunds.provided.card.numbernu este obligatoriu. Gateway-ul va extrage toate detaliile relevante ale cardului din datele utile furnizate.posTerminal.serialNumber:sourceOfFunds.provided.card.p2pe.cardBinsourceOfFunds.provided.card.p2pe.encryptionState: Dacă nu completați acest câmp, gateway-ul va utilizaVALIDca valoare implicităsourceOfFunds.provided.card.p2pe.initializationVector: Acest câmp poate fi omis dacă terminalul nu utilizează un vector de inițializare pentru a iniția criptarea.
- Completați câmpurile obligatorii.
- Completați câmpurile opționale, dacă este necesar.
Referință API P2PE [REST][NVP]
Tabelul de mai jos rezumă limitările câmpurilor pentru grupul de parametri sourceOfFunds.provided.card.p2pe.
| Dacă câmpul | atunci gateway-ul... | ||
|---|---|---|---|
sourceOfFunds.provided.card.p2pe. initializationVector |
sourceOfFunds.provided.card.p2pe. keySerialNumber |
sourceOfFunds.provided.card.p2pe. payload | |
| este completat | este completat | nu este completat | respinge solicitarea de tranzacție. |
| este completat | este completat în clar, înainte sau după decriptare | este completat | returnează o eroare și generează un element în jurnalul de securitate. |
Răspuns de tranzacție
Câmpul sourceOfFunds.provided.card.encryption returnează DUKPT (începând cu webServices Integration versiunea 43) în răspunsul de tranzacție pentru a indica criptarea datelor de pe card. Câmpurile din grupul de parametri sourceOfFunds.provided.card.p2pe nu sunt returnate în răspuns.
Integrare pentru utilizare PIN online
PIN-ul online introdus de posesorul cardului este criptat la sursă, pe dispozitivul de introducere a PIN-ului. ARC Pay Gateway acceptă datele PIN online criptate prin DUKPT (Derived Unique Key Per Transaction – cheie unică derivată per tranzacție) începând cu webServices Integration versiunea 45.
- Furnizați datele PIN criptate prin DUKPT de la terminal în următoarele câmpuri:
sourceOfFunds.provided.card.pin.payloadsourceOfFunds.provided.card.pin.keySerialNumberposTerminal.pinLengthCapabilitysourceOfFunds.provided.card.pin.encryptionState
- Completați câmpurile obligatorii.
- Completați câmpurile opționale, dacă este necesar.
Integrarea pentru utilizarea mPOS
Gateway-ul acceptă plățile pe dispozitive POS mobile (mPOS) începând cu API v56. Pentru a activa funcționalitatea, furnizați următoarele elemente în tranzacția Verify, Authorize, Capture, Pay sau Refund:
posTerminal.cardholderActivated=MPOS_ACCEPTANCE_DEVICE- Furnizați o valoare a cititorului de carduri în
posTerminal.mobile.cardInputDevice
BUILT_IN: Telefon mobil sau tabletă cu un singur cititor contactless încorporat. În acest caz, posTerminal.pinEntryCapability trebuie setată la SOFTWARE_ONLINE_PIN_ONLY, altfel gateway-ul respinge tranzacția.INTEGRATED_DONGLE: Terminal mobil dedicat cu un cititor de carduri integrat. În acest caz, posTerminal.pinEntryCapability trebuie setată la PIN_SUPPORTED sau OFFLINE_PIN_ONLY, altfel gateway-ul respinge tranzacția.SEPARATE_DONGLE: Dispozitiv nou sau terminal mobil dedicat cu un cititor de carduri separat. În acest caz, posTerminal.pinEntryCapability trebuie setată la PIN_SUPPORTED sau OFFLINE_PIN_ONLY, altfel gateway-ul respinge tranzacția.
- Completați câmpurile obligatorii.
- Completați câmpurile opționale, dacă este necesar.
Răspuns de tranzacție
Autentificarea cu PIN poate eșua dacă plătitorul introduce un PIN nevalid, depășește numărul permis de încercări de introducere a PIN-ului sau omite introducerea PIN-ului atunci când PIN-ul este necesar pentru finalizarea tranzacției.
În aceste scenarii, în care autorizarea eșuează din cauza unei erori de autentificare cu PIN, gateway-ul va returna anumite coduri de răspuns pentru autentificare. Puteți reutiliza același ID de comandă la tranzacția următoare.
Testare integrare prezență posesor de card
Vă puteți testa integrarea folosind cardurile de testare specifice achizitorului dvs.