Gebruik:

Om uw API key en secret te gebruiken voor authorizatie via de OAuth 2.0-methode, kunt u de volgende stappen volgen:

1. Maak een autorisatieverzoek naar de API-server met uw API key en secret via de Basic-authenticatiemethode. U moet de Authorization header gebruiken om uw gecodeerde API key en secret mee te sturen.
2. Als reactie op uw autorisatieverzoek ontvangt u een access token van de API-server. Dit access token geeft u toegang tot de API.
3. Stuur een API-verzoek naar de server met het access token in de Authorization header via de Bearer-authenticatiemethode.

Zorg ervoor dat u de API key en secret veilig bewaart, aangezien deze vertrouwelijke informatie bevatten en de toegang tot uw API beveiligen. Wij adviseren u om uw API key en secret op een veilige plek op te slaan en ze niet te delen met ongeautoriseerde personen.

Voor meer informatie over de specifieke stappen en vereisten om de OAuth 2.0-methode te gebruiken met uw API, verwijzen wij u naar de API-documentatie en -handleiding.

// Vervang "API_KEY" door uw eigen API key
$apiKey = "sleutel:geheim";
$base64EncodedApiKey = base64_encode($apiKey);

// Gebruik de $base64EncodedApiKey in de Authorization header
$headers = [
    "Authorization: Basic " . $base64EncodedApiKey
];

// Voer het HTTP-verzoek uit, bijvoorbeeld met curl
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://rest-api.pinvandaag.com/V2");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
curl_close($ch);

Er is een nieuwe flow in de REST-API dit is de aanbevolen methode van authenticatie op het V2 Rest API van Pin Vandaag.

1. U dient een X-API-KEY header mee te sturen naar de API met u API KEY. Verwar deze niet met de secret. De secret is echter niet meer nodig en mag weggelaten worden bij deze methode.
2. Stuur de REQUEST en de server stuurt de bijhorende correcte response terug.

// Vervang "API_KEY" door uw eigen API key
$apiKey = "sleutel";

$headers = [
    "X-API-KEY: $apiKey",
];

// Voer het HTTP-verzoek uit, bijvoorbeeld met curl
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://rest-api.pinvandaag.com/V2");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
curl_close($ch);

Opmerkbare veranderingen

Met de introductie van versie 2 van onze API geven we nu de juiste HTTP-statuscodes terug, afhankelijk van wat er gebeurt bij een API-aanroep. Dit biedt verschillende voordelen:

1. Betere foutafhandeling: ontwikkelaars kunnen nu de juiste acties ondernemen op basis van de statuscode, waardoor de API-integratie stabieler en betrouwbaarder wordt.
2. Snellere probleemoplossing: als er een fout optreedt in de API-aanroep, kunnen ontwikkelaars snel de oorzaak van het probleem identificeren op basis van de statuscode die wordt geretourneerd.
3. Efficiëntere ontwikkeling: met de juiste statuscodes kunnen ontwikkelaars hun integratieproces efficiënter maken en sneller hun integratie voltooien.

In tegenstelling tot versie 1 van onze API, waarbij geen specifieke HTTP-statuscodes werden geretourneerd, biedt versie 2 van onze API een betere en robuustere manier van werken met de API.

Transactie aanmaken

Met behulp van deze methode kunt u een nieuwe transactie aanmaken.

Let op: Als u de paymentUrl wilt gebruiken, is het belangrijk om ook de returnUrl mee te geven aan de API. Anders wordt u steeds naar dezelfde pagina verwezen.

Deze methode werkt voor de volgende typen terminals: CCV en WorldLine.

Verplichte parameters:

• terminal_id (de terminal waarop de transactie moet worden gestart)
• Bearer Authenticatie / X-API-KEY header (zie #gebruikswijze)
• amount (het te betalen bedrag in centen)

Optionele parameters:

• CallbackUrl (webhook-URL)
• OwnReference (eigen referentie)
• ReturnUrl (alleen voor CCV: de URL waarnaar u teruggestuurd wilt worden)

Wij streven ernaar om u een hoogwaardige dienstverlening te bieden en willen u graag helpen bij het gebruik van onze API. Mocht u nog vragen of opmerkingen hebben, neem dan gerust contact met ons op.

Voorbeeld CURL-oproep:

curl --location --request POST 'https://rest-api.pinvandaag.com/V2/instore/transactions/start' \
--header 'X-API-KEY: API_TOKEN' \
--form 'terminal_id="TERMINAL_ID"' \
--form 'amount="AMOUNT_IN_CENTS"'

RESPONSES

Success:

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

 

Status

Met deze functie kunt u de status van een betalingstransactie ophalen.

Notities:

1. Het is belangrijk om te weten dat bij CCV een transactie elke 30 seconden wordt bijgewerkt wanneer de statusfunctie wordt aangeroepen. Dit doen we om de flow van CCV te respecteren. Wanneer u meerdere keren binnen deze tijdslimiet dezelfde transactie opvraagt, ontvangt u dezelfde transactie zonder updates omdat wij de transactie aan onze kant bijwerken.

Deze methode werkt voor de volgende typen terminals: CCV en WorldLine.

Verplichte parameters:

• terminal_id (de terminal waarop de transactie heeft plaatsgevonden)
• Bearer Authenticatie / X-API-KEY header (zie #gebruikswijze)
• transaction_id (het ID van de transactie)

Voorbeeld CURL-oproep:

curl --location --request POST 'https://rest-api.pinvandaag.com/V2/instore/transactions/status' \
--header 'X-API-KEY: API_TOKEN' \
--form 'terminal_id="TERMINAL_ID"' \
--form 'transaction_id="TRANSACTION_ID"'

RESPONSES

CCV Terminals

SUCCESS

{
    "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\",\"  ================\"]"
}

ERROR

{
    "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

SUCCESS

{
    "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,\"\"]]"
}

ERROR

{
    "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
}

Transactie annuleren

Met deze functie kunt u een betalingstransactie annuleren die op dat moment wordt verwerkt op de terminal. Let op: deze functie annuleert alleen transacties die op de terminal worden verwerkt.

Let op (CCV)!

Om de flow van CCV te respecteren, kan een transactie slechts 3 keer worden aangevraagd om te annuleren. Dit is een aparte benadering, omdat het annuleren van een transactie vanuit CCV niet altijd even gemakkelijk is. Hoewel we momenteel geen alternatief kunnen bieden voor dit aspect, blijven we streven naar het verbeteren van onze technologie. Na 3 verzoeken zal de API u automatisch ratelimiteren en zal het niet langer mogelijk zijn om deze bewerking uit te voeren voor de betreffende transactie die op CCV-terminals is gemaakt.

Deze methode werkt alleen voor de volgende typen terminals: WorldLine & CCV (expirimenteel).

Verplichte parameters:

• Terminal ID (de terminal waarop de transactie plaats heeft gevonden) (alleen Worldline)
• Bearer Authenticatie / X-API-KEY header (zie #gebruikswijze)
• Transactie ID (Alleen voor CCV)

Voorbeeld CURL-oproep:

WorldLine

curl --location --request POST 'https://rest-api.pinvandaag.com/v2/instore/terminal/stop' \
     --header 'X-API-KEY: API_TOKEN' \
     --form 'terminal_id="TERMINAL_ID"' \
     --form 'key="API_KEY"'

CCV

curl --location --request POST 'https://rest-api.pinvandaag.com/v2/instore/transactions/cancel' \
     --header 'Authorization: Bearer ACCESS_TOKEN' \
     --form 'transaction_id="TRANSACTIE_ID"' \
     --form 'key="API_KEY"'

Bon per mail opsturen

Met behulp van deze functie kunt u een bon meesturen naar uw klant als onderdeel van de geslaagde transactie. Let op: deze functie werkt alleen bij geslaagde transacties.

Deze methode werkt voor de volgende typen terminals: CCV en WorldLine.

Verplichte parameters:

Voorbeeld CURL-oproep:

curl --location --request POST 'https://rest-api.pinvandaag.com/V2/instore/transactions/mail' \
     --header 'X-API-KEY: API_TOKEN' \
     --form 'terminal_id="TERMINAL_ID"' \
     --form 'transaction_id="TRANSACTIE_ID"' \
     --form 'email="EMAIL_ADRES_VAN_ONTVANGER"'

 

Terugstorting

Met behulp van deze functie kunt u een terugbetaling starten op het pinapparaat.

Deze methode werkt alleen voor de volgende typen terminals: WorldLine.

Verplichte parameters:

• terminal_id (de terminal waarop de terugbetaling wordt uitgevoerd)
• Bearer Authenticatie / X-API-KEY header (zie #gebruikswijze)
• amount (het bedrag dat moet worden terugbetaald in centen)

Voorbeeld CURL-oproep:

curl --location --request POST 'https://rest-api.pinvandaag.com/V2/instore/transactions/refund' \
     --header 'X-API-KEY: API_TOKEN' \
     --form 'terminal_id="TERMINAL_ID"' \
     --form 'amount="BEDRAG_IN_CENTEN"'

 

CTMP

Met behulp van deze functie kunt u een CTMP-verzoek sturen naar een WorldLine terminal.

Met CTMP kan de WorldLine-terminal handmatig een nieuwe configuratie ophalen vanaf de WorldLine-server.

Deze methode werkt alleen voor de volgende typen terminals: WorldLine.

Verplichte parameters:

• terminal_id (de terminal waarnaar het CTMP-verzoek wordt gestuurd)
• Bearer Authenticatie /  X-API-KEY header (zie #gebruikswijze)

Voorbeeld CURL-oproep:

curl --location --request POST 'https://rest-api.pinvandaag.com/V2/instore/transactions/ctmp' \
    --header 'X-API-KEY: API_TOKEN' \
    --form 'terminal_id="TERMINAL_ID"'

 

Transactie lijst

Met onze API is het heel eenvoudig om een lijst met transacties op te halen van de gewenste terminals. Deze functie werkt voor zowel WorldLine als CCV terminals.

Verplichte headers:

• Bearer Authenticatie / X-API-KEY header: authenticatiegegevens (zie #gebruikswijze)

Om de transactielijst op te halen, zijn de volgende verplichte parameters nodig:

•  terminal_id: het ID van de terminal waarvan de transacties moeten worden opgehaald
•  maximale grootte van de op te halen transacties (1 tot 100)
•  page: welke pagina van de transactielijst moet worden opgehaald

Optionele parameters (query parameters) zijn:

– datefrom: de datum waarop de transacties moeten beginnen, in UNIX-tijdstempelnotatie
– dateto: de datum waarop de transacties moeten eindigen, in UNIX-tijdstempelnotatie

voorbeeld CURL-oproep:

curl --location --request GET 'https://rest-api.pinvandaag.com/V2/instore/transactions/TERMINAL_ID/LIMIT/PAGE/?datefrom=FROM_TIMESTAMP&dateto=TO_TIMESTAMP' \
--header 'X-API-KEY: API_TOKEN' 

Het is belangrijk om op te merken dat de datum- en tijdsnotatie in UNIX-tijdstempelnotatie moet zijn en dat de “tot” datum niet eerder mag zijn dan de “vanaf” datum om ervoor te zorgen dat de gewenste transacties worden opgehaald.

Met deze eenvoudige API-functie kunt u snel en gemakkelijk de gewenste transacties ophalen.

Laatste transactie ophalen (NIEUW)

De API biedt nu een nieuwe mogelijkheid om de laatste transactie op te halen per terminal. Deze functie werkt voor CCV & Worldline.

Verplichte headers:

• Bearer authenticate / X-API-KEY header (zie #gebruikswijze)

Voorbeeld CURL-Oproep:

curl --location --request POST 'https://rest-api.pinvandaag.com/V2/instore/transactions/last_transaction' \
    --header 'X-API-KEY: API_TOKEN' \
    --form 'terminal_id="TERMINAL_ID"'

Status codes:
200 (OK) Geeft resultaat terug voorbeeld:

{
    "id": 1,
    "status": "failed",
    "terminal": "12345678",
    "amount": 1,
    "transaction_id": "123456789",
    "own_reference": "",
    "which_api": "Worldline|CCV",
    "created_at": "2024-04-05T00:00:00+00:00",
    "updated_at": "2024-04-05T00:00:00+00:00",
    "callback_url": "", // Default a string (also if empty)
    "payment_url": null | string,
    "receipt": null | string,
    "incident_code": "1",
    "error_msg": "",
    "cancel_counter_ccv": null | number (int),
}

Deze test response heeft notering zoals number (int), string & enzovoort... Dit is puur gedaan, zodat er geen fouten aan u kant gemaakt worden. Dus deze notaties zijn puur verwachte data types die terug kan krijgen vanuit onze rest api.

Bijvoorbeeld:
null | number (int) houd in: het is null, of het kan een integer terug geven.
null | string houd in: het geeft of null of een string terug met de verwachte waarde.

De // is puur een opmerking vanuit onze kant. Officieel kan JSON geen comments hebben maar dit is puur gedaan uit zorgvuldigheid van onze kant. Als de // er staat, kan de waarde geen null terug geven.

400 Ongeldige POST body meegegeven. Wat er precies mis gaat of ontbreekt kom terug in het response als volgt:

{
    "status": "error",
    "http_code": 400,
    "message": {
        "error": "Invalid data was provided.",
        "validation_errors": {
            "terminal_id": {
                "integer": "The Terminal id must be integer"
            }
        }
    },
    "data": null
}

404 (Terminal niet gevonden of geen transacties)

500 INTERNAL SERVER ERROR. In dit geval neem contact op met development team van Pin Vandaag: [email protected]