UnionPay SecurePay voor Webservices API

  Laatst bijgewerkt: 

 

CW59.png

UnionPay, ook bekend als China UnionPay (CUP), is een kaartsysteem dat actief is op het Chinese vasteland en in Oost- en Zuidoost-Azië. SecurePay is een dienst van UnionPay die de browser van de kaarthouder tijdens het afrekenproces naar hun servers leidt, waar zij vóór de aankoop worden geverifieerd en gevraagd worden hun kaartgegevens in een beveiligde omgeving in te voeren. Klanten kunnen ook de QR-code scannen die op de betaalpagina wordt weergegeven met een UnionPay-app of andere ondersteunde apps. Na de betaling wordt de klant teruggeleid naar uw website en ontvangt u een bevestiging via een URL-kennisgeving.

  Ondersteunde landen   Alle landen die UnionPay-kaarten uitgeven, met uitzondering van gesanctioneerde landen.
  Ondersteunde munteenheden   AUD, CAD, CHF, CNY, EUR, GBP, HKD, JPY, NZD, SGD, USD
  Terugbetalingen

  Volledige en gedeeltelijke terugbetalingen zijn toegestaan tot 6 maanden.

  Terugboekingen

  Betalingen kunnen worden teruggevorderd.

  Zero-authorisation

  Niet ondersteund.

  Terugkerende betalingen

  Niet ondersteund.

 

Configuratie

Om UnionPay SecurePay op uw account in te schakelen, neemt u contact op met uw accountmanager.
Er wordt een testzandbakaccount verstrekt, die u nodig hebt om uw implementatie te testen.

 

Procesoverzicht

  1. Initieer de klant
    • De klant gaat akkoord met een betaling via UnionPay SecurePay op de website van de handelaar.
    • Merchant dient AUTH verzoek in om de sessie te starten, inclusief de successfulurlredirect en errorurlredirect.
    • Merchant ontvangt AUTH antwoord, inclusief redirecturl.

  2. Doorverwijzen naar UnionPay SecurePay
    • Merchant stuurt de browser van de klant door naar de redirecturl.
    • De klant volgt de instructies op de gehoste pagina's van UnionPay om de betaling te autoriseren.
    • Indien succesvol, wordt de browser doorgestuurd naar de successfulurlredirect, een door de handelaar gehoste pagina die de bevestiging van de betaling weergeeft.
    • Als er een probleem is geweest met de betaling, wordt de browser doorgestuurd naar de errorurlredirect, een door de handelaar gehoste pagina die de klant een foutmelding geeft.

  3. Voltooiing van de betaling
    • Op een later tijdstip zal UnionPay contact opnemen met Trust Payments met de bevestiging dat het geld is betaald.
    • Trust Payments zal een URL-kennisgeving naar het systeem van de handelaar sturen om te bevestigen dat het geld is betaald.
    • De handelaar ontvangt de kennisgeving en antwoordt om Trust Payments te informeren dat de kennisgeving met succes is ontvangen.

 

1. Initieer de klant

Wanneer de klant ervoor kiest om te betalen met UnionPay SecurePay, moet uw systeem een AUTH verzoek uitvoeren en, indien succesvol, de browser van de klant omleiden naar de URL die in het antwoord wordt geretourneerd.

 

AUTH verzoek

Het onderstaande voorbeeld betreft een verzoek op UnionPay SecurePay AUTH :

Python PHP cURL Ruwe JSON Ruwe XML
#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth = {
"currencyiso3a": "CNY",
"requesttypedescription": "AUTH",
"accounttypedescription": "ECOM",
"sitereference": "test_site12345",
"baseamount": "1050",
"paymenttypedescription": "UNIONPAY",
"successfulurlredirect": "https://yourwebsite.com",
"errorurlredirect": "https://yourwebsite.com",
"billingfirstname": "Joe",
"billinglastname": "Bloggs",
"billingcountryiso2a": "CN"
}

strequest = securetrading.Request()
strequest.update(auth)
stresponse = st.process(strequest) #stresponse contains the transaction response

Vervang <DOMAIN> met een ondersteund domein. Klik hier voor een volledige lijst.

 

Specificatie veld

  Veld Formaat Beschrijving
X1-EN.png accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) Alleen "ECOM" (e-commerce) wordt ondersteund.
X1-EN.png baseamount
XPath: /billing/amount
Numeriek (13) Het bedrag van de transactie in basiseenheden, zonder komma's of decimalen, dus €10 wordt ingediend als 1000. Deze waarde moet groter zijn dan nul. (De maximumlengte kan variëren, afhankelijk van uw wervende bank - Neem contact op met uw bank voor meer informatie)
X1-EN.png billingcountryiso2a
XPath: /billing/country
Alpha (2)

Het land voor het factuuradres van de klant. Dit moet in ISO2A-formaat zijn.

Voor een lijst van door UnionPay SecurePay ondersteunde landcodes, zie de lijst bovenaan deze pagina.

X1-EN.png currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3)

De Munt waarin de transactie zal worden verwerkt (in ISO3A-formaat).

Voor een lijst van Munt codes die worden ondersteund door UnionPay SecurePay, zie de lijst bovenaan deze pagina.

X1-EN.png errorurlredirect
XPath: /merchant/errorurlredirect
URL (2048) De URL waarnaar de klant wordt teruggestuurd na een fout op de door UnionPay gehoste pagina's.
X1-EN.png paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) Deze waarde moet worden ingediend als "UNIONPAY".
X1-EN.png requesttypedescription
XPath: /@type
Alpha (20) De waarde in het verzoek moet "AUTH" zijn.
X1-EN.png sitereference
XPath: /operation/sitereference
Alfanumeriek
& underscore (50)
De site referentie heeft betrekking op uw individuele account die u bij de installatie hebt ontvangen. Als u uw site referentie niet kent, neem dan contact op met ons Support Team.
X1-EN.png successfulurlredirect
XPath: /merchant/successfulurlredirect
URL (2048) De URL waarnaar de klant wordt teruggestuurd na een succesvolle autorisatie door UnionPay.
X2-EN.png billingprefixname
XPath: /billing/name/prefix
Alfanumeriek, inclusief
symbolen (25)

Het voorvoegsel van de factuurnaam van de klant (bv. De heer, Juffrouw, Dr.).

Ten minste één van de velden met de factureringsnaam is verplicht.

X2-EN.png billingfirstname
XPath: /billing/name/first
Alfanumeriek, inclusief
symbolen (127)

De klant Voornaam facturatie.

Ten minste één van de velden met de factureringsnaam is verplicht.

X2-EN.png billingmiddlename
XPath: /billing/name/middle
Alfanumeriek, inclusief
symbolen (127)

De middelste factureringsnaam of -namen van de klant.

Ten minste één van de velden met de factureringsnaam is verplicht.

X2-EN.png billinglastname
XPath: /billing/name/last
Alfanumeriek, inclusief
symbolen (127)

De klant Achternaam facturatie.

Ten minste één van de velden met de factureringsnaam is verplicht.

X2-EN.png billingsuffixname
XPath: /billing/name/suffix
Alfanumeriek, inclusief
symbolen (25)

Het achtervoegsel van de factureringsnaam van de klant (bv. Bsc).

Ten minste één van de velden met de factureringsnaam is verplicht.

X3-EN.png orderreference
XPath: /merchant/orderreference
Alfanumeriek, inclusief symbolen (25)

 

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.

Uw unieke bestelreferentie die in het Trust Payments systeem kan worden opgeslagen.

 

AUTH antwoord

Python PHP Ruwe JSON Ruwe XML
{
u'requestreference': u'An3ug1kap',
u'version': u'1.00',
u'responses': [{
u'transactionreference': u'23-86-113',
u'merchantname': u'Test Merchant',
u'paymenttypedescription': u'UNIONPAY',
u'settleduedate': u'2017-03-16',
u'baseamount': u'1050',
u'transactionstartedtimestamp': u'2017-03-16 16:25:08',
u'errormessage': u'Ok',
u'settlestatus': u'10',
u'accounttypedescription': u'ECOM',
u'errorcode': u'0',
u'redirecturl': u'https://example.com',
u'acquirertransactionreference': u'12',
u'acquirersecret': u'q9gy5ppgdyd5fh60kfe2j0f26peu2xww',
u'requesttypedescription': u'AUTH',
u'acquirerresponsemessage': u'PENDING',
u'operatorname': u'webservices@example.com',
u'livestatus': u'0',
u'currencyiso3a': u'CNY'
}]
}

 

Specificatie veld

  Veld Formaat Beschrijving
X4-EN.png accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) De geretourneerde waarde is "ECOM".
X4-EN.png acquirersecret
XPath: /acquirersecret
Alfanumeriek (64) Gebruikt door Trust Payments om het antwoord van de verwerver te verifiëren. (Uw systeem hoeft dit niet te verifiëren)
X4-EN.png acquirertransactionreference
XPath: /acquirertransactionreference
Alfanumeriek, inclusief symbolen (127) Unieke Transactiereferentie toegewezen door UnionPay.
X4-EN.png baseamount
XPath: /billing/amount
Numeriek (13) Het bedrag van de transactie in basiseenheden, zonder komma's of decimalen, dus €10 wordt geretourneerd als 1000.
X4-EN.png currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3)

De Munt waarin de transactie werd verwerkt (in ISO3A-formaat).

Voor een lijst van Munt codes die worden ondersteund door UnionPay SecurePay, zie de lijst bovenaan deze pagina.

X4-EN.png errorcode
XPath: /error/code
Numeriek (1-5) De foutcode (errorcode) moet worden gebruikt om te bepalen of het verzoek succesvol was of niet.
  • Als de foutcode "0" is, is de transactie geslaagd.
  • Als de foutcode (errorcode) niet "0" is, was de transactie niet succesvol.

Klik hier voor een volledige lijst van errorcode en berichtwaarden.

X4-EN.png errormessage
XPath: /error/message
Alfanumeriek (255) Dit is het bericht dat overeenkomt met de bovenstaande code.

Klik hier voor een volledige lijst van errorcode en berichtwaarden.

X4-EN.png livestatus
XPath: /live
Numeriek (1)
  • 0 - Transactie verwerkt met een testrekening.
  • 1 - Transactie verwerkt met een live rekening.
X4-EN.png operatorname
XPath: /merchant/operatorname
Alfanumeriek (255) De waarde van dit veld bevat de naam van de gebruiker die het verzoek heeft verwerkt.
X4-EN.png paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) De geretourneerde waarde is "UNIONPAY".
X4-EN.png redirecturl
XPath: /other/redirecturl
URL (255) Stuur de browser van de klant door naar deze URL, zodat hij de betaling kan voltooien op de gehoste pagina's van UnionPay.
X4-EN.png requesttypedescription
XPath: /@type
Alpha (20) De geretourneerde waarde is "AUTH".
X4-EN.png settleduedate
XPath: /settlement/settleduedate
Datum JJJJ-MM-DD De datum waarop de transactie zal worden afgewikkeld.
X4-EN.png settlestatus
XPath: /settlement/settlestatus
Numeriek (3) Hiermee kunt u de status van de betaling bepalen. Raadpleeg het gedeelte " Omgaan met het antwoord " hieronder voor informatie over hoe u dit veld het best kunt interpreteren.
X4-EN.png transactionreference
XPath: /transactionreference
Alfanumeriek, inclusief
koppeltekens (25)
Een unieke referentie voor de transactie, toegewezen door Trust Payments.
X4-EN.png transactionstartedtimestamp
XPath: /timestamp
Datum tijd JJJJ-MM-DD hh:mm:ss Het tijdstip waarop de transactie werd verwerkt.
X2-EN.png acquirerresponsemessage
XPath: /acquirerresponsemessage
Alfanumeriek (255)

Gebruikt door uw verwerver om het resultaat van het verzoek aan te geven.

Dit varieert afhankelijk van uw wervende bank. Neem contact op met uw bank voor meer informatie.

X2-EN.png errordata
XPath: /error/data
Alfanumeriek (255)

Aanvullende informatie om te helpen bij het oplossen van de fout.

Wordt alleen geretourneerd als er een fout is opgetreden.

X2-EN.png merchantname
XPath: /merchant/merchantname
Alfanumeriek (255)

Dit zijn gegevens die verband houden met de rekening die is gebruikt om de transactie te verwerken.

Om deze velden te wijzigen, gelieve neem contact op met ons Support Team.

Hangt af van uw account configuratie.

 

Behandeling van het antwoord

De settlestatus teruggestuurd in het antwoord op AUTH wordt gebruikt om de status van de betaling op UnionPay SecurePay te bepalen:

  Als de settlestatus is "10", is de betaling in behandeling. afwikkeling

  • Het geld is nog niet op uw bankrekening gestort.
  • De volgende stap is het omleiden van de browser van de klant naar de redirecturl om de betaling te voltooien.

Het geld wordt pas op uw rekening gestort als de klant wordt doorgestuurd naar de pagina's van UnionPay om de betaling te voltooien. Lees verder voor meer informatie.

  • Wanneer er een update is van de Status betaling van de AUTH, ontvangt u een URL-kennisgeving om u te informeren dat de settlestatus is bijgewerkt tot "3" of "100".
  • Nadere informatie over de kennisgevingen is hieronder te vinden.

  Als de settlestatus is "3", de betaling is geannuleerd.

  • De betaling is geweigerd, of er is een fout opgetreden.
  • Om meer te weten te komen over waarom de betaling niet is gelukt, moet u kijken naar de errorcode. bijv. "70000" geeft aan dat de betaling is geweigerd. Klik hier voor een volledige lijst met foutcodes.

Naast het bovenstaande bevelen wij ook aan na de betaling aanvullende controles te verrichten.

 

2. Doorverwijzen naar UnionPay SecurePay

Uw systeem moet de browser van de klant omleiden naar de redirecturl, een door UnionPay gehoste pagina om de betaling te verwerken.

  De redirecturl binnen een iframe. Hierdoor wordt de inhoud niet correct weergegeven en kan de betaling uiteindelijk niet succesvol worden afgerond.

Op een later tijdstip wordt de klant teruggestuurd naar de successfulurlredirect of de errorurlredirect verstrekt in het AUTH verzoek.

  Als de klant wordt doorverwezen naar de successfulurlredirect:

De klant heeft de vereiste stappen op de pagina's van UnionPay met succes doorlopen.
Aanbevolen acties: Toon bevestiging dat de betaling succesvol was.

  Als de klant wordt doorverwezen naar de errorurlredirect:

De klant heeft een probleem ondervonden waardoor hij de betaling niet heeft kunnen voltooien.
Aanbevolen acties: Informeer de klant dat er een probleem was met de betaling, waarbij voldoende transactiedetails worden weergegeven zodat de klant de betalingspoging kan navragen.

  Bij het testen krijgt u de sandbox te zien zoals die door UnionPay wordt aangeboden. Om een testtransactie te voltooien, moet u de instructies op het scherm volgen. Neem contact op met uw accountmanager voor testgegevens die u in de zandbak kunt invoeren.

 

3. Voltooiing van de betaling

Zodra de klant terugkeert van de UnionPay hosted pagina naar de successfulurlredirect of errorurlredirect gehost op uw site, moet u respectievelijk een bevestigings- of foutmelding weergeven.

  Controleer of er regels voor URL-omleidingen zijn ingeschakeld in de Regelbeheer op uw site referentie(s), aangezien deze in strijd kunnen zijn met en voorrang kunnen hebben op de successfulurlredirect en errorurlredirect velden in het AUTH verzoek.

Zodra een betaling is geautoriseerd, wordt het geld op een later tijdstip verrekend, zoals bepaald door UnionPay.

  Het proces afwikkeling voor UnionPay SecurePay verschilt van het standaardproces dat wordt gevolgd bij betaalmethoden met een kaart.

  De afwikkeling kennisgeving mag niet onmiddellijk na de verwerking van de AUTH

In het onwaarschijnlijke geval dat de betaling na 7 dagen nog in behandeling is bij afwikkeling (settlestatus "10"), zal dit worden ingepland voor onderzoek en zullen wij contact met u opnemen voor verdere informatie.

Voordat u begint met testen, raden wij u aan contact op te nemen met ons Support Team en te verzoeken dat regels worden ingeschakeld op uw account, die URL-kennisgevingen naar uw systeem sturen in de volgende scenario's:

  • Wanneer een betaling is goedgekeurd.
  • Als de fondsen vereffend zijn.

 

Configuratie van de autorisatie melding

Wij raden u aan ten minste de volgende velden op te nemen in uw autorisatie kennisgeving:

  • Antwoordbericht aankoper (acquirerresponsemessage)
  • Basisbedrag (baseamount) (bijv. 10,50 pond is "1050")*.
  • Hoofdbedrag (mainamount) (bijv. 10,50 pond is "10,50")*.
  • Land facturatie (billingcountryiso2a)
  • Munt (currencyiso3a)
  • Foutcode (errorcode)
  • Live Status (livestatus)
  • Bestelreferentie (orderreference)
  • Betalingstype (paymenttypedescription)
  • Verzoektype (requesttypedescription)
  • Status betaling (settlestatus)
  • Site referentie (sitereference)
  • Transactiereferentie (transactionreference)
  • Tijdstempel start transactie (transactionstartedtimestamp)

*Kies uw voorkeursformaat.

 

Configuratie van de afwikkeling melding

Wij raden u aan de volgende velden op te nemen in uw afwikkeling kennisgeving:

  • Status betaling (settlestatus)
  • Site referentie (sitereference)
  • Transactiereferentie (transactionreference)

 

Controleer de kennisgeving

U moet de inhoud van elke ontvangen kennisgeving controleren en dienovereenkomstig reageren door de in onze URL-kennisgevingen documentatie. In het bijzonder moet u kijken naar de bijgewerkte settlestatus waarde:

  • Op autorisatie: Als de settlestatus "0", "1" of "10" is, is de betaling geautoriseerd en hoeft u op dit moment geen verdere actie te ondernemen. Waarden van "2" of "3" geven echter aan dat de fondsen niet gepland voor afwikkeling (opgeschort en geannuleerd, respectievelijk).
  • Op afwikkeling: Als de settlestatus is bijgewerkt tot "100", betekent dit dat het geld is vereffend. Als dit echter is bijgewerkt tot "3", betekent dit dat er een probleem is geweest en dat de betaling vervolgens is geannuleerd.

  Geannuleerde transacties (settlestatus "3") kan op een later tijdstip worden afgewikkeld. In situaties waarin de klant de voor de uitvoering van de betaling vereiste stappen heeft voltooid, wordt de settlestatus wordt bijgewerkt tot "100" om aan te geven dat het geld naar uw rekening is overgemaakt.

Als u contact hebt opgenomen met het Support Team om afwikkeling meldingen te configureren (zoals hierboven beschreven), wordt u op de hoogte gebracht wanneer dit gebeurt.

 

Test

U moet uw oplossing testen voordat u live betalingen kunt gaan verwerken. Testtransacties worden verwerkt via uw test site referentie.

  Vereisten

U moet contact opnemen met ons Support Team en uw UnionPay SecurePay testaccountgegevens doorgeven. Wij zullen dan uw test site referentie configureren om rechtstreeks verbinding te maken met de UnionPay SecurePay testomgeving.

Bij het uitvoeren van testtransacties zal de redirect URL in het antwoord op AUTH uw browser omleiden naar de UnionPay SecurePay testomgeving om een betaling te simuleren. Verder is het proces precies hetzelfde als bij live betalingen.

 

Terugbetalingen

Na het verwerken van een betaling met UnionPay SecurePay, is het mogelijk om de klant terug te betalen door een REFUND verzoek in te dienen.

Restituties voor UnionPay SecurePay worden onmiddellijk verrekend (settlestatus "100").

 

Vereisten

  • U kunt een betaling pas terugstorten wanneer de AUTH is vereffend (settlestatus op "100" staat).
  • U kunt niet een hoger bedrag terugbetalen dan oorspronkelijk was verrekend.

Het verzoek REFUND en het antwoord voor UnionPay SecurePay betalingen volgen dezelfde veldspecificatie als in onze standaard REFUND documentatie. Klik hier voor meer informatie.

Was dit artikel nuttig?
0 van de 0 vonden dit nuttig