U hebt een gebruikersaccount nodig met de rol "Webservices JWT" om het token aan te maken.
Als deze gebruikersaccount nog niet is aangemaakt, vraag er dan een aan voor uw site(s) door contact op te nemen met ons Support Team.
De jwt veld dat in het formulier wordt verzonden, moet de vorm hebben van een JSON Web Token (JWT), dat bestaat uit gecodeerde gegevens.
JSON Web Tokens zijn een open, industriestandaard RFC 7519 methode voor het veilig verzenden van gegevens tussen twee partijen.
We raden aan de bibliotheken te gebruiken die te vinden zijn op https://jwt.io om de JWT te genereren.
De jwt-aanmaak moet worden uitgevoerd op uw backendserver om de blootstelling van gevoelige details (d.w.z. JWT-ondertekeningsgeheim) te vermijden.
In zijn compacte vorm bestaat JWT uit drie delen, gescheiden door punten ("."), namelijk:
<header>.<payload>.<signature>
Het genereren van de header
De header bestaat uit twee delen:
- alg - Het gebruikte ondertekeningsalgoritme (wij ondersteunen "HS256", "HS384" en "HS512").
- typ - Het type van het token, dat "JWT" is.
Deze moeten Base64URL gecodeerd zijn om het eerste deel van het JWT te vormen. Voorbeeld:
- Header – {“alg”:”HS256″,”typ”:”JWT”}
- Encoded - eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
Belangrijk: Ingezonden gegevens moeten Base64Url gecodeerd zijn, in plaats van standaard Base64.
Het genereren van de payload
Bij het indienen van velden in de payloadvolg dan de onderstaande aanbevelingen:
- De payload moet bevatten alle velden die u de klant niet wilt laten wijzigen (bijvoorbeeld het transactiebedrag).
- De payload mag niet bevatten alle velden die de klant mag wijzigen tijdens het afrekenen (bijvoorbeeld zijn adres of contactgegevens).
Deze velden worden dan Base64URL gecodeerd om het tweede deel van het JWT te vormen. Voorbeeld:
{
"iss": "jwt.user",
"iat": 1730900533,
"payload": {
"currencyiso3a": "GBP",
"orderreference": "MyOrder123",
"sitereference": "test_12345",
"accounttypedescription": "ECOM",
"requesttypedescriptions": ["THREEDQUERY","AUTH"],
"baseamount": "1050"
}
}
eyJpc3MiOiJqd3QudXNlciIsImlhdCI6MTczMDkwMDUzMywicGF5bG9hZCI6eyJjdXJyZW5jeWlzbzNhIjoiR0JQIiwib3JkZXJyZWZlcmVuY2UiOiJNeU9yZGVyMTIzIiwic2l0ZXJlZmVyZW5jZSI6InRlc3RfMTIzNDUiLCJhY2NvdW50dHlwZWRlc2NyaXB0aW9uIjoiRUNPTSIsInJlcXVlc3R0eXBlZGVzY3JpcHRpb25zIjpbIlRIUkVFRFFVRVJZIiwiQVVUSCJdLCJiYXNlYW1vdW50IjoiMTA1MCJ9fQ
De baseamount veld getoond in de payload Bovenstaand voorbeeld bevat een waarde in basiseenheden. Dit betekent dat de waarde zonder het decimaalteken, dus £10,50 zou worden opgegeven als "1050".
Wij staan u toe om in plaats daarvan de mainamount hier, indien gewenst. In dit geval wordt de waarde opgegeven in hoofdeenheden (£10,50 zou worden opgegeven als "10.50" - let op de decimale punt).
Overwegingen voor Mail Order Telephone Order (MOTO) payloads
- "accounttypedescription = MOTO" moet worden ingediend.
- Anders dan bij ECOM transacties, is 3-D Secure niet van toepassing op MOTO, dus je kunt "THREEDQUERY" uit het requesttypedescriptions veld uitsluiten wanneer u uw JWT payload aanmaakt.
Het genereren van de signature
Het laatste deel van het teken is de signature. De signature wordt gebruikt om ervoor te zorgen dat het token niet is gewijzigd door de klant voordat het verzonden formulier Trust Payments bereikt.
De signature wordt gemaakt door de gecodeerde header, de gecodeerde payload, a “secret” en het algoritme gespecificeerd in de header, en dan ondertekenen.
De “secret” is een geheime wachtwoordzin (in stringformaat) die u moet opnemen bij het ondertekenen van het JWT. Dit moet afgesproken met ons Support Team voorafgaand aan de verwerking van verzoeken aan ons systeem.
Bij het opslaan van de waarde van de “secret” op uw systeem, moet u ervoor zorgen dat u dit op een veilige manier doet.
De waarde van de “secret” mag niet worden opgeslagen in platte tekst.
Voorbeeld - Als u het HMAC SHA256-algoritme wilt gebruiken, is het signature zou op de volgende manier worden gecreëerd:
HMACSHA256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
secret)
De laatste stap is ervoor te zorgen dat de signature is Base64URL gecodeerd.
Het ondertekenen van tokens met een private sleutel wordt niet ondersteund.
Volledig JWT-voorbeeld
Het resultaat is drie Base64URL-strings, gescheiden door punten ("."):
Als we de header, de payload en de signature van bovenstaande voorbeelden, zou u uitkomen op het volgende JWT:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJqd3QudXNlciIsImlhdCI6MTczMDkwMDUzMywicGF5bG9hZCI6eyJjdXJyZW5jeWlzbzNhIjoiR0JQIiwib3JkZXJyZWZlcmVuY2UiOiJNeU9yZGVyMTIzIiwic2l0ZXJlZmVyZW5jZSI6InRlc3RfMTIzNDUiLCJhY2NvdW50dHlwZWRlc2NyaXB0aW9uIjoiRUNPTSIsInJlcXVlc3R0eXBlZGVzY3JpcHRpb25zIjpbIlRIUkVFRFFVRVJZIiwiQVVUSCJdLCJiYXNlYW1vdW50IjoiMTA1MCJ9fQ.yFKDJyWUK7vTBMP9KjiKVzsplSBddrGi_yPeeCJgEgU
Het volledige token kan dan worden opgenomen bij het initialiseren van de bibliotheek, als volgt:
<html>
<head>
</head>
<body>
<div id="st-notification-frame"></div>
<form id="st-form" action="https://www.example.com" method="POST">
<div id="st-card-number"></div>
<div id="st-expiration-date"></div>
<div id="st-security-code"></div>
<button type="submit">Pay securely</button>
</form>
<script src="<CDN_DOMAIN>"></script>
<script>
(function() {
var st = SecureTrading({
jwt : 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJqd3QudXNlciIsImlhdCI6MTczMDkwMDUzMywicGF5bG9hZCI6eyJjdXJyZW5jeWlzbzNhIjoiR0JQIiwib3JkZXJyZWZlcmVuY2UiOiJNeU9yZGVyMTIzIiwic2l0ZXJlZmVyZW5jZSI6InRlc3RfMTIzNDUiLCJhY2NvdW50dHlwZWRlc2NyaXB0aW9uIjoiRUNPTSIsInJlcXVlc3R0eXBlZGVzY3JpcHRpb25zIjpbIlRIUkVFRFFVRVJZIiwiQVVUSCJdLCJiYXNlYW1vdW50IjoiMTA1MCJ9fQ.yFKDJyWUK7vTBMP9KjiKVzsplSBddrGi_yPeeCJgEgU'
});
st.Components();
})();
</script>
</body>
</html>
Vervang <CDN_DOMAIN> met een ondersteund domein. Klik hier voor een volledige lijst.
Bijwerken van het JWT tijdens de betalingssessie
Er zijn omstandigheden waarin u misschien uw systeem wilt configureren om het JWT bij te werken na het eerste verzoek, maar vóór de voltooiing van de betaling.
Bijvoorbeeld wanneer de klant een donatie doet en gevraagd wordt een aangepast bedrag te kiezen. Omdat het bedrag moet worden opgenomen in het JWT om te voorkomen dat derden ongeoorloofde wijzigingen aanbrengen, zou u het JWT tijdens de betalingssessie moeten bijwerken zodra het definitieve bedrag is vastgesteld.
Klik hier voor instructies over hoe dit te configureren.
JWT-veldspecificatie
| Veld | Formaat | Beschrijving | ||
| JWT Payload |
|
|||
| iat | Numeriek (17) |
Tijd in seconden sinds Unix epoch (gegenereerd met UTC). Klik hier voor meer informatie. Het JWT is 1 uur geldig vanaf het tijdstip dat in het iat. Zodra de JavaScript Library met dit JWT is geïnitialiseerd, heeft de klant 15 minuten om de transactie te voltooien. |
||
| iss | Alfanumeriek (255) | Uw JWT-gebruikersnaam. | ||
| Payload Object | ||||
| accounttypedescription | Alfanumeriek (20) |
Voor E-Commerce (ECOM) oplossingen, geef "ECOM" op in dit veld. Voor MOTO oplossingen, geef "MOTO" op in dit veld. Afhankelijk van de vereisten. Neem contact op met Support voor assistentie. |
||
| authmethod | Alfanumeriek (5) |
De volgende waarden worden ondersteund: De inhoud van authmethod hebben geen invloed op de afwikkeling status van de transactie. afwikkeling status kan worden gecontroleerd met behulp van settlestatus en settleduedate. Klik hier voor meer informatie over het proces afwikkeling . |
||
| billingprefixname | Alfanumeriek (25) | Het voorvoegsel voor de factuurnaam, uit de volgende lijst: De heer, De heren, Juffrouw, Dr., Mw, Prof., Eerw., Dhr., Heer, Dame & Mx. | ||
| billingfirstname | Alfanumeriek (127) |
De Voornaam facturatie. Vereist voor Visa Secure Data Field Mandate. Vereist voor handelaren in kansspelen. |
||
| billingmiddlename | Alfanumeriek (127) | De facturatie middelste naam. | ||
| billinglastname | Alfanumeriek (127) |
De Achternaam facturatie. Vereist voor Visa Secure Data Field Mandate. Vereist voor handelaren in kansspelen. |
||
| billingsuffixname | Alfanumeriek (25) | De naam van het achtervoegsel voor facturering. | ||
| billingpremise | Alfanumeriek (25) |
Het huisnummer of de eerste regel van het factuuradres. |
||
| billingstreet | Alfanumeriek (127) |
Het huisnummer of de eerste regel van het factuuradres. |
||
| billingtown | Alfanumeriek (127) |
De stad die is ingevoerd voor het factuuradres. |
||
| billingcounty | Alfanumeriek (127) |
Provincie facturatie. Opmerking: Indien ingediend, billingcountryiso2a is vereist. |
||
| billingpostcode | Alfanumeriek (25) |
De Postcode facturatie of postcode moet geldig zijn voor de billingcountryiso2a ingediend. |
||
| billingcountryiso2a | iso2a |
Land facturatie in iso2a formaat.
Verplicht als billingcounty is ingediend. Anders, optioneel. |
||
| billingemail | E-mail (255) |
E-mailadres facturatie adres. Vereist voor Visa Secure Data Field Mandate wanneer billingtelephone niet is voorzien. |
||
| billingtelephone |
Alfanumeriek, inclusief symbolen (20) |
Telefoonnummer voor facturering. Geldige tekens:
Vereist voor Visa Secure Data Field Mandate wanneer billingemail niet is voorzien. |
||
| billingtelephonetype | Char (1) |
Type facturering telefoonnummer:
|
||
| credentialsonfile | Numeriek (1) |
De volgende waarden kunnen worden ingediend:
Dit is vereist voor Visa en Mastercard transacties waarbij de merchant gebruik maakt van de CoF functie. Als de transactie niet in aanmerking komt voor CoF, of als je de referenties niet wilt gebruiken voor toekomstige transacties, kun je dit veld weglaten. Visa en Mastercard hebben bepaald dat u toestemming van de kaarthouder moet krijgen voordat u kaartgegevens opslaat voor toekomstig gebruik.
|
||
| customerprefixname | Alfanumeriek (25) | Leveringsnaam. | ||
| customerfirstname | Alfanumeriek (127) | |||
| customermiddlename | Alfanumeriek (127) | |||
| customerlastname | Alfanumeriek (127) | |||
| customersuffixname | Alfanumeriek (25) | |||
| customerpremise | Alfanumeriek (25) |
Leveringsadres. De leveringspostcode of postcode moet geldig zijn voor de customercountryiso2a ingediend. |
||
| customerstreet | Alfanumeriek (127) | |||
| customertown | Alfanumeriek (127) | |||
| customercounty | Alfanumeriek (127) | |||
| customercountryiso2a | iso2a | |||
| customerpostcode | Alfanumeriek (25) | |||
| customeremail | E-mail (255) | E-mailadres van de bezorger. | ||
| customertelephone |
Alfanumeriek, inclusief symbolen (20) |
Telefoonnummer aflevering. Geldige tekens:
|
||
| customertelephonetype | Char (1) |
Type levering telefoonnummer:
|
||
| customfield1 | Alfanumeriek (100) |
Met deze velden kunnen aangepaste gegevens worden ingediend en opgeslagen in Trust Payments' records. Deze gegevens kunnen later worden opgehaald door een CSV uit te voeren Transactie downloaden.
Gebruiksvoorbeeld: U vindt het misschien nuttig voor afstemming om het verkoopbedrag en de fooi afzonderlijk in twee van deze aangepaste velden op te nemen, zoals baseamount/mainamount velden zijn het totaal van beide. |
||
| customfield2 | ||||
| customfield3 | ||||
| customfield4 | ||||
| customfield5 | ||||
| currencyiso3a | iso3a |
De Munt waarin de transactie werd verwerkt. |
||
| baseamount | Numeriek (13) |
Ofwel baseamount of mainamount moet worden opgenomen (niet allebei).
Het bedrag van de transactie in basiseenheden (zonder zonder decimalen). Bijvoorbeeld €10,50 wordt ingediend als "1050". |
||
| mainamount | Numeriek (14) |
Ofwel baseamount of mainamount moet worden opgenomen (niet allebei).
Het bedrag van de transactie in hoofdeenheden. |
||
| initiationreason | Char (1) |
Dit is vereist bij het verwerken van een Merchant Initiated Transaction (MIT). Hiermee kunt u een reden voor de transactie toewijzen. Niet indienen bij het verwerken van een door de klant geïnitieerde transactie (CIT). De toegestane waarden voor dit veld zijn "A", "C", "D", "S" en "X".
Zie Visa's eigen documentatie voor meer informatie. |
||
| locale | Ongedefinieerd |
Standaard worden het afrekeningsformulier en eventuele foutmeldingen weergegeven in het Brits Engels. Maar dit gedrag kan worden omzeild door het volgende in te voeren locale waarden in de payload:
|
||
| operatorname | Alfanumeriek (255) | De waarde van dit veld bevat de naam van de gebruiker die het verzoek heeft verwerkt. Dit is optioneel. Indien weggelaten, wordt de waarde van de alias geregistreerd, die ofwel uw site referentie of Web Services gebruikersnaam zal zijn, afhankelijk van uw configuratie. | ||
| orderreference |
Alfanumeriek (25) Zie beschrijving rechts voor verdere details |
Uw unieke bestelreferentie die in het Trust Payments systeem kan worden opgeslagen. Wij raden u ten zeerste aan een orderreference voor elke transactie. Aanbevolen lengte 25 tekens of minder (exacte lengte afhankelijk van de wervende bank). Niet-naleving van deze eis kan ertoe leiden dat de tekst in de transactie wordt ingekort. |
||
| parenttransactionreference | Alfanumeriek, inclusief koppeltekens (25) | Hiermee kunt u de transactionreference van een eerder verzoek. De belangrijkste details zijn overgenomen van dit verzoek. | ||
| requesttypedescriptions | Lijst |
De te verwerken verzoektypes. Belangrijk: Voor e-commerce (ECOM) transacties moet u ervoor zorgen dat “THREEDQUERY” in deze lijst wordt ingediend bij het uitvoeren van transacties, om ervoor te zorgen dat 3-D Secure wordt verwerkt. Dit is vereist door de PSD2 mandaat. Klik hier voor meer informatie over ondersteunde verzoektypes. |
||
| scaexemptionindicator | Numeriek (1) |
Gebruikt om de aard van 3-D Secure authenticatie te beïnvloeden in scenario's waar dit is toegestaan. Opmerking: Alleen ondersteund door bepaalde acquirerende banken. Neem contact op met het Support Team voor meer informatie. Geef een van de volgende waarden op wanneer u een transactie vrijstelt van authenticatie:
Neem contact op met uw verwerver om na te gaan of u vrijstellingen mag toepassen voordat u dat probeert. U kunt ook een van de volgende waarden invoeren om te vragen dat step up (uitdaging) authenticatie wordt uitgevoerd:
|
||
| settleduedate | Datum JJJJ-MM-DD |
Hier kunt u instellen op welke dag in de toekomst uw transactie moet worden afgewikkeld. Dit moet in het formaat zijn: JJJJ-MM-DD. |
||
| settlestatus | Numeriek (3) |
Een numerieke waarde die wordt gebruikt om de instructie afwikkeling te definiëren.
|
||
| sitereference | Alfanumeriek (50) | Unieke referentie die uw Trust Payments site identificeert. | ||
| subscriptionbegindate | Datum JJJJ-MM-DD |
Optioneel bij het plannen van abonnementen. Dit veld verwijst naar de datum waarop de eerste geautomatiseerd betaling zal worden verwerkt. Vanaf dat moment gebruiken wij de gegevens die in de subscriptionunit en subscriptionfrequency velden om de abonnementsbetalingen op gezette tijden automatisch te verwerken. bijv. Als een abonnementsaanvraag wordt ingediend op 5 januari 2018 het interval is 1 MONTH (subscriptionfrequency = 1 and subscriptionunit = MONTH) en subscriptionbegindate is 2018-01-08, de eerste automatische betaling wordt verwerkt op 8 januari 2018, en alle volgende betalingen worden verwerkt op de 8e van elke maand. Als u de subscriptionbegindate, zullen we de subscriptionunit en subscriptionfrequency velden hierboven om de eerste automatische betaling automatisch te plannen. |
||
| subscriptionfinalnumber | Numeriek (5) |
Vereist bij het plannen van abonnementen. Dit wordt gebruikt om het aantal te verwerken betalingen in de loop van het abonnement in te stellen:
Opmerking: Als de waarde "0" is, plant de Abonnementsmodule betalingen voor onbepaalde tijd totdat de gebruiker het abonnement handmatig op Inactief zet. |
||
| subscriptionfrequency | Numeriek (11) |
Vereist bij het plannen van abonnementen. Gecombineerd met subscriptionunit, de frequentie bepaalt hoe vaak de betalingen worden verwerkt. Bijvoorbeeld voor een betaling om de 7 dagen: subscriptionfrequency = 7 en subscriptionunit = DAY bijvoorbeeld voor een betaling om de 2 maanden: subscriptionfrequency = 2 en subscriptionunit = MONTH |
||
| subscriptionnumber | Numeriek (5) |
Optioneel bij het plannen van abonnementen. Tenzij anders vermeld, beginnen abonnementen met subscriptionnumber = 1. De subscriptionnumber wordt automatisch verhoogd bij elke volgende abonnementsbetaling totdat het de waarde van de subscriptionfinalnumber veld, wanneer geen verdere betalingen zullen worden geprobeerd. Een voltooid abonnement wordt weergegeven door een subscriptionnumber die hoger is dan de overeenkomstige subscriptionfinalnumber. |
||
| subscriptiontype | Alpha (11) |
Vereist bij het plannen van abonnementen. Dit veld geeft het type abonnement aan dat moet worden verwerkt. Uw systeem kan deze twee waarden indienen:
*INSTALLMENT wordt ondersteund voor winkeliers met een Trust Payments acquiring account. Als u een andere acquiring bank gebruikt, moet u neem contact op met ons Support Team om te controleren of deze functie wordt ondersteund alvorens verder te gaan. |
||
| subscriptionunit | Alfa (5) |
Vereist bij het plannen van abonnementen. Dit veld vertegenwoordigt de tijdseenheid tussen elk abonnement. Dit kan zijn “DAY” of “MONTH”. Let op: Het is absoluut noodzakelijk dat dit veld in HOOFDLETTERS (“DAY” of “MONTH”). |
||
|
threedbypasspaymenttypes
|
Lijst | Om te voldoen aan PSD2, moet u 3-D Secure authenticatie uitvoeren bij alle ondersteunde kaartgebaseerde e-commercetransacties. Dit wordt bereikt door ervoor te zorgen dat THREEDQUERY is opgenomen in de requesttypedescriptions lijst in de JWT payload. Uw oplossing kan echter te maken krijgen met omstandigheden waarin 3-D Secure niet vereist / ondersteund wordt door uw wervende bank. Door betalingstypen te specificeren in de threedbypasspaymenttypes lijst wordt 3-D Secure authenticatie niet uitgevoerd voor de bovengenoemde betalingswijzen. | ||
| transactionactive | Numeriek (1) |
Optioneel bij het plannen van abonnementen. De abonnementsstatus. "0" - Inactief: Schort toekomstige betalingen op totdat deze handmatig worden opgeheven. "1" - Actief: Plant onmiddellijk abonnementsbetalingen, waarbij fraude en dubbele controles worden omzeild (indien ingeschakeld). "2" - In afwachting (standaard): Plannen van abonnementsbetalingen nadat de AUTH is betaald (settlestatus "100"). |
||
Uw vooruitgang
Nu u uw betalingsformulier hebt gemaakt, de JavaScript Library hebt geconfigureerd en uw JWT hebt opgenomen, raden wij u aan webhooks te configureren om ervoor te zorgen dat u op de hoogte wordt gebracht van transacties die op uw rekening zijn verwerkt.
