paymentic.com (1.0.0)

Dokumentacja do API Paymentic

Paymentic przesyła notyfikacje o zmianach np. w statusie transakcji. Każda notyfikacja zawiera swój unikalny identyfikator prezentowany w nagłówku X-Paymentic-Notification-Id można uznać go za klucz idempotentności ponieważ notyfikacje ponawiane są zgodnie ze schematem dostępnym poniżej.

Aby poinformować, że Partner prawidłowo odebrał i przetworzył powiadomienie należy zwrócić kod HTTP 200 z Content-Type: plain/text i zawartością body OK lub kod HTTP 202 z pustym body

Przykładowy request przesłany do strony partnera

GET /yourpath HTTP/1.1
Host: yourdomain.com
User-Agent: Paymentic/1.0
Content-Type: application/json
Content-Length: 170
X-Paymentic-Event: TRANSACTION_STATUS
X-Paymentic-Notification-Id: 01j96yn02bhbv8j1jjtk36zn2t
X-Paymentic-Time: 2024-09-20T09:48:03+02:00
X-Paymentic-Signature: 5Fil+PMpabLxsKwo3rWj9+o6gAi4ub93fismBewbYz46mHt7pjPHcHELUVw8McZ5nUb3feMVVBl+dPzXq2XgLQ==
{"transactionId":"FJRS-LY7-3W0-30K9","pointId":"000cb241","status":"CREATED","amount":10,"currency":"PLN","commission":null,"custom":null,"channelId":null,"isTest":false}

Wszystkie notyfikacje są ponawiane zgodnie z implementacją wzorca integracyjnego Retry Pattern

Schemat ponawiania notyfikacji (Retry Policy)

Jeżeli ponawianie notyfikacji nie zakończony się powodzeniem, zostanie przerwane po 30 powiadomieniach (Circuit Breaker)

Paymentic przy każdej notyfikacji przesyła sygnaturę w nagłówku X-Paymentic-Signature

Sygnatura notyfikacji może zostać obliczona za pomocą HASH HMAC SHA512 (RFC 6234).

Struktura do generowania sygnatury

W strukturze należy złączyć wartości (konkatenacja) z nagłówków i body oddzielając jest | (Unicode U+007C) w kolejności: X-Paymentic-Event, User-Agent(Wersja z user-agenta np. 1.0), Body, X-Paymentic-Notification-Id, X-Paymentic-Time

TRANSACTION_STATUS|1.0|{"transactionId":"FJRS-LY7-3W0-30K9","pointId":"000cb241","status":"CREATED","amount":10,"currency":"PLN","commission":null,"custom":null,"channelId":null,"isTest":false}|01j96yn02bhbv8j1jjtk36zn2t|2024-09-20T09:48:03+02:00

Przykłady jak wygenerować sygnaturę w różnych językach

PHP

<?php
$signatureKey = '99ab572393014a7c2f20fe53253fc37819371a033c4507055e94e816683b9c8d';
echo base64_encode(hash_hmac('sha512', 'TRANSACTION_STATUS|1.0|{"transactionId":"FJRS-LY7-3W0-30K9","pointId":"000cb241","status":"CREATED","amount":10,"currency":"PLN","commission":null,"custom":null,"channelId":null,"isTest":false}|01j96yn02bhbv8j1jjtk36zn2t|2024-09-20T09:48:03+02:00', $signatureKey, true));

Python

import hashlib
import hmac
import base64

signatureKey = '99ab572393014a7c2f20fe53253fc37819371a033c4507055e94e816683b9c8d'
message = 'TRANSACTION_STATUS|1.0|{"transactionId":"FJRS-LY7-3W0-30K9","pointId":"000cb241","status":"CREATED","amount":10,"currency":"PLN","commission":null,"custom":null,"channelId":null,"isTest":false}|01j96yn02bhbv8j1jjtk36zn2t|2024-09-20T09:48:03+02:00'

signature = hmac.new(signatureKey.encode('utf-8'), message.encode('utf-8'), hashlib.sha512).digest()
encoded_signature = base64.b64encode(signature).decode('utf-8')

print(encoded_signature)

Przetestuj generowanie sygnatury

Przykładowy request przesłany do strony partnera

GET /yourpath HTTP/1.1
Host: yourdomain.com
User-Agent: Paymentic/1.0
Content-Type: application/json
Content-Length: 201
X-Paymentic-Notification-Id: 01J5SXAG3D5MZXCZQ4P567ECQ8
X-Paymentic-Time: 1724226165
X-Paymentic-Signature: 8XYkwtl7wbjf74DUPFab0GP6/us4u91xHectfnxsqr0GQ9aU8Wj/l/g7BSyuwilQ2oVY1Yppnci5/z4CaRPtWQ==
{"transactionId":"CR6-75T-KVY-DAV4","pointId":"e99ed63d","status":"PENDING","amount":14.24,"currency":"PLN","commission":null,"custom":null,"msisdn":"48987654321","mccmnc":null,"isTest":false}

Ponawianie notyfikacji

Próba

Sygnatura notyfikacji może zostać obliczona za pomocą HMAC SHA512.

Struktura do generowania sygnatury

1.0|{"transactionId":"CR6-75T-KVY-DAV4"}|01J5SXAG3D5MZXCZQ4P567ECQ8|1724226165

Klucz do sygnatury używany do wygenerowania przykładowej sygnatury d3d2503c-478e-405d-b453-33e63b1ce962

Przykładowa syngatura z danych podanych wyżej

ZKpOXsLkxz95TL5MLK4owl6WZ66489XDR6M9BayCmH2u4zbzeePho/FsHoxlgvwO2rEZ5njJ0puxgLiCQYoi2w==

Przykłady jak wygenerować sygnaturę w różnych językach

PHP

<?php
$signatureKey = 'd3d2503c-478e-405d-b453-33e63b1ce962';
echo base64_encode(hash_hmac('sha512', '1.0|{"transactionId":"CR6-75T-KVY-DAV4"}|01J5SXAG3D5MZXCZQ4P567ECQ8|1724226165', $signatureKey, true));

Przetestuj generowanie sygnatury

API DirectBilling pozwala zwracać całość pobranej kwoty za daną transakcję bezpośrednio na konto użytkownika. Zworty realizowane są przez operatorów. Po utworzeniu zwrotu otrzyma on status CREATED następnie musi zostać zaakceptowany przez Paymentic

Aktualnie realizacja możliwa jest tylko u operatora Orange mncmcc 26003

W przypadku gdy spróbujemy zlecić zwrot dla transakcji, w której występował nieobsługowany operator otrzymamy odpowiedź z kodem 400 i errorCode TRANSACTION_PROVIDER_NOT_SUPPORTED

W przypadku gdy spróbujemy zlecić zwrot dla starszej transakcji niż dozwolony czas, otrzymamy response z kodem 400 i errorCode TRANSACTION_TOO_OLD