rest api

Info voordat u begint met de integratie

De rest-API heeft koppelingen met zowel CCV en WorldLine om de service te bieden. Omdat dit 2 verschillende koppelingen zijn die ook nog eens anders werken kan het voorkomen dat een functie bij WorldLine wel werkt en niet bij CCV. Voordat u begint bekijk de documentatie over de verschillende methodes goed en houd hier ook rekening mee. Als er een methode niet werkt bij een van de 2 soorten pin apparaten dan wordt dit ook aangegeven. Ook kan het voorkomen dat er iets andere gegevens terug worden gestuurd.

Benodigdheden

• Terminal ID
• Api token (door ons wordt deze geleverd)

Happy flow

1. Client stuurt een request naar de server
2. Server behandelt deze request en roept de pin apparaat aan
3. Pin apparaat wordt wakker en wacht op een betaling
4. Betaling op het apparaat is geslaagd en de server stuurt een webhook terug naar de client
5. Einde transactie

create

Middels deze methode kunt u een transactie aanmaken.

Let op! wanneer u de paymentUrl wilt gebruiken dan is het ook verstandig om de returnUrl mee te geven aan de API. Anders wordt u steeds naar dezelfde pagina verwezen.

Methode werkt voor de volgende type terminals:

• CCV
• WorldLine

Params:

verplichte parameters

• terminalId ( de terminal waar de transactie op gestart moet worden)
• key ( de API key )
• amount ( hoeveel er betaald moet worden in centen )

optionele parameters

• callbackUrl ( webhook url )
• ownReference ( eigen referentie )
• returnUrl ( {CCV} dan wordt u terug verwezen naar de url die u hier aangeeft )

CURL voorbeeld:

curl --location --request POST 'https://rest-api.pinvandaag.com/V1/instore/transactions/create' \
     --form 'terminalId="TERMINAL_ID"' \
     --form 'key="API_KEY"' \
     --form 'amount="AMOUNT"'

Responses:

Success status:

{
    "transactionId": "2405102",
    "status": "started",
    "amount": 1,
    "terminal": "50303253",
    "createdAt": "2022-06-25 17:10:36",
    "callbackUrl": null,
    "ownReference": null
}

status

Middels deze functie kunt u de status van de transactie ophalen.

Methode werkt voor de volgende type terminals:

• CCV
• WorldLine

Params:

verplichte parameters

• terminalId ( de terminal waar de transactie heeft plaatsgevonden )
• key ( de API key )
• transactionId ( de id van de transactie )

CURL voorbeeld:

curl --location --request POST 'https://rest-api.pinvandaag.com/V1/instore/transactions/status' \
     --form 'terminalId="TERMINAL_ID"' \
     --form 'key="API_KEY"' \
     --form 'transactionId="TRANSACTION_ID"'

Responses:

Success status:

CCV terminals:

{
    "transactionId": "TL220611120248997CB8FB114.1",
    "status": "success",
    "amount": 0,
    "terminal": "706249441",
    "createdAt": "2022-06-11 12:01:29",
    "callbackUrl": null,
    "paymentUrl": null,
    "errorMsg": null,
    "ownReference": null,
    "receipt": "[\" Kopie Kaarthouder\",\" \",\"Terminal: CT695868  Merchant: 21830001  \",\"Periode: 2162       Transactie: 00000026\",\"Token: 1009216201031965010          \",\"Contactloze betaling\",\" (A0000000043060)\",\"Kaart: 673703xxxxxxxxx5008\",\"Kaartnr: 03     \",\" \",\"BETALING\",\"11/06/2022 12:03    Auth. code:   D4O226\",\" \",\"Totaal:     0,01 EUR\",\" \",\"      AKKOORD\"]",
    "journalReceipt": "[\"                JOURNAAL\",\" \",\"Terminal: CT695868  Merchant: 21830001  \",\"Periode: 2162       Transactie: 00000026\",\"Token: 1009216201031965010          \",\" (A0000000043060)\",\"Kaart: 673703xxxxxxxxx5008\",\"Kaartnr: 03     \",\" \",\"BETALING\",\"11/06/2022 12:03    Auth. code:   D4O226\",\" \",\"Totaal:     0,01 EUR\",\"      AKKOORD\",\"ACQUIRER ID:    52800002\",\"TRANSACTION TREATMENT RES. 0000\",\"  ================\"]"
}

WorldLine terminals:

{
    "transactionId": "2340636",
    "status": "success",
    "amount": 1,
    "terminal": "50303253",
    "createdAt": "2022-06-18 16:23:45",
    "callbackUrl": null,
    "incidentCode": null,
    "errorMsg": null,
    "ownReference": null,
    "receipt": "[[0,\"POI: 50303253\\r\"],[0,\"KLANTTICKET\\r\"],[0,\"--------------------------------------\\r\"],[0,\"Terminal:                     CT695867\\r\"],[0,\"Merchant:                     21830001\\r\"],[0,\"Periode:                          2169\\r\"],[0,\"Transactie:                   00000006\\r\"],[0,\"Token:             1009216902435162019\\r\"],[0,\"\\r\"],[0,\"\\r\"],[0,\"Maestro\\r\"],[0,\"(A0000000043060)\\r\"],[0,\"Kaart:             673703xxxxxxxxx5008\\r\"],[0,\"Kaartserienummer:                    3\\r\"],[0,\"\\r\"],[0,\"BETALING\\r\"],[0,\"Datum:                18\\/06\\/2022 16:24\\r\"],[0,\"Autorisatiecode:                E3G3A8\\r\"],[0,\"\\r\"],[0,\"\\r\"],[0,\"Totaal:                       0,01 EUR\\r\"],[0,\"\\r\"],[0,\"Contactless\\r\"],[0,\"Leesmethode: CHIP\\r\"],[0,\"\"]]"
}

Failed status:

CCV terminals:

{
    "transactionId": "TL220618175406586CB893D27.2",
    "status": "failed",
    "amount": 1,
    "terminal": "706249441",
    "createdAt": "2022-06-18 17:53:46",
    "callbackUrl": null,
    "receipt": null,
    "paymentUrl": "https://redirect.jforce.be/terminal/poll?reference=TL220618175406586CB893D27.2",
    "errorMsg": "processing_error",
    "ownReference": null
}

WorldLine terminals:

{
    "transactionId": "2340627",
    "status": "failed",
    "amount": 1,
    "terminal": "50303253",
    "createdAt": "2022-06-18 16:22:39",
    "callbackUrl": null,
    "receipt": null,
    "incidentCode": "2628",
    "errorMsg": "External Equipment Cancellation",
    "ownReference": null
}

cancel

Middels deze functie kunt u een transactie annuleren die bezig is op de terminal. Deze functie annuleert alleen transacties die op de terminal bezig zijn.

Methode werkt voor de volgende type terminals:

• WorldLine

Params:

verplichte parameters

• terminalId ( de terminal waar de transactie op loopt )
• key ( de API key )

CURL voorbeeld:

curl --location --request POST 'https://rest-api.pinvandaag.com/V1/instore/terminal/cancel' \
     --form 'terminalId="TERMINAL_ID"' \
     --form 'key="API_KEY"'

Success Response:

{
    "status": "success",
    "message": "transaction has been cancelled"
}

mailReceipt

Middels deze functie kunt u een bon meesturen naar de klant. Deze functie werkt alleen met geslaagde transacties.

Methode werkt voor de volgende type terminals:

• CCV
• WorldLine

Params:

verplichte parameters

• terminalId ( de terminal waar de transactie op is geslaagd )
• key ( de API key )
• transactionId ( de id van de transactie )
• recipientEmail ( de email van de ontvangende )

optionele parameters

• recipientName ( naam van de ontvanger )
• mailSubject ( Onderwerp van de mail )
• mailBody ( inhoud van de mail in HTML formaat )

curl --location --request POST 'https://rest-api.pinvandaag.com/V1/instore/transactions/mailreceipt' \
     --form 'terminalId="TERMINAL_ID"' \
     --form 'key="API_KEY"' \
     --form 'transactionId="TRANSACTION_ID"' \
     --form 'recipientEmail="RECIPIENT_EMAIL"'

Success Response:

{
    "status": "success",
    "message": "mail sent to recipient@mail.nl"
}

refund

Middels deze functie kunt u een terugbetaling starten op het pinapparaat.

Methode werkt voor de volgende type terminals:

• WorldLine

Params:

Verplichte paramaters

• terminalId ( de terminal waar de terugbetaling op gedaan wordt )
• key ( de API key )
• amount ( hoeveel er terug betaald moet worden in centen )

curl --location --request POST 'https://rest-api.pinvandaag.com/V1/instore/transactions/refund' \
     --form 'terminalId="TERMINAL_ID"' \
     --form 'key="API_KEY"' \
     --form 'amount="AMOUNT"'

Success Response:

{
    "transactionId": "1234567",
    "status": "started",
    "amount": 1,
    "terminal": "12345678",
    "createdAt": "2022-06-25 18:17:42",
    "callbackUrl": null
}

ctmp

Middels deze functie kunt u een ctmp request richting een WorldLine terminal sturen.

Methode werkt voor de volgende type terminals:

• WorldLine

Params:

Verplichte paramaters

• terminalId ( de terminal waar de terugbetaling op gedaan wordt )
• key ( de API key )

curl --location --request POST 'https://rest-api.pinvandaag.com/V1/instore/terminal/ctmp' \
    --form 'terminalId="TERMINAL_ID"' \
    --form 'key="API_KEY"'

Success Response:

{
    "status": "success",
    "message": "CTMP request has been send"
}

date

Middels deze functie kunt u transacties ophalen tussen 2 aangegeven tijden. De API levert deze per honderd transacties terug.

Methode werkt voor de volgende type terminals:

• WorldLine
• CCV

Params:

Verplichte parameters

• terminalId ( de terminal waar de transacties van worden opgehaald)
• key ( de API key )
• from ( vanaf deze datum worden alle transacties opgehaald format: YYYY-MM-DD )
• to ( tot aan deze datum worden alle transacties opgehaald format: YYYY-MM-DD )

Optionele parameters

• page ( als de hoeveelheid data meer dan 100 is dan kunt u deze parameter gebruik om de volgende 100 transacties op te halen )

curl --location --request POST 'https://rest-api.pinvandaag.com/V1/instore/transactions/date' \
    --form 'terminalId="TERMINAL_ID"' \
    --form 'key="API_KEY"' \
    --form 'from="2022-02-01"' \
    --form 'to="2022-07-13"' \
    --form 'page="1"'