Użyj wstępnie autoryzowanego przechwytywania, gdy klient jest obciążany (całkowicie lub częściowo) dopiero po dostarczeniu towarów lub usług.
Przepływ ten przypomina przepływ „jednorazowego zakupu”, ale wymagany jest dodatkowy krok, aby faktycznie obciążyć klienta za towary lub usługi – Capture.
Przechwycenie może dotyczyć całkowitej kwoty zakupu lub jej części, w którym to przypadku akceptowanych jest wiele przechwyceń do pełnej kwoty autoryzacji.
Przed rozpoczęciem
Stwórz zamówienie z wymaganymi danymi i zagwarantować następujące informacje:
- Uwzględnij typ płatności, kwotę, walutę i dozwolone metody płatności;
- Jeśli jesteś już pewien, że wymagana jest tylko płatność kartą, wpisz tylko „CARD” w liście transaction.paymentMethod ;
Upewnij się, że transaction.paymentType posiada wartość „AUTH”.
Generowanie transakcji
Należy pamiętać, że poniższe żądanie wymaga Nagłówka Autoryzacji z transactionSignature zwróconego z operacji kasowania.
W zapytaniu, Bearer Token jest zastępowany odpowiedzią checkout’u transactionSignature.
Parametry nagłówka
Parametry zapytania
string <= 40 characters
The security code (CVV/CVC) associated with the credit card.
string
The name of the cardholder as it appears on the credit card.
boolean
A flag indicating whether to create a token for future use or not (true/false).
Przykład:
{
"cardInfo": {
"PAN": "5236410030000927",
"secureCode": "776",
"validationDate": "2026-05-26T00:00:00.000Z",
"cardholderName": "Jane Smith",
"createToken": false
}
}Oczekiwana odpowiedź
Pomyślna odpowiedź techniczna składa się ze statusu HTTP-200 i wartości returnStatus.statusCode=”000″.
PaymentStatus w odpowiedzi informuje o tym, czy sama transakcja została zaakceptowana, odrzucona, nadal oczekuje na ostateczny wynik lub wymaga podjęcia dodatkowych działań.
- Success: Autoryzacja została pomyślnie przetworzona, a środki klienta zostały zweryfikowane.
- Pending: Ostateczny wynik autoryzacji nie jest jeszcze znany. Będziesz musiał sprawdzać status tej transakcji, dopóki nie osiągnie ona ostatecznego stanu lub nie zdecydujesz się jej anulować.
- Declined: Zezwolenie zostało odrzucone.
- Partial: Autoryzacja została częściowo zaakceptowana, ale wymaga wykonania dodatkowych czynności (np. uwierzytelnienia 3D-Secure). ActionResponse zawiera instrukcje dotyczące dalszego postępowania.
Dokonaj przyszłych przechwyceń:
Capture służy do żądania rozliczenia wcześniej autoryzowanych środków.
Żądanie Capture jest wykonywane przy użyciu poprzedniej płatności pre-autoryzacji (AUTH) poprzez odniesienie do jej transactionID i wysyłanie POST zapyania po HTTPS do /payments/{transactionID}/ endpoint’u przechwytywania.
Przechwytywanie może odbywać się na różne sposoby:
- Pełną, pobrać pełną autoryzowaną kwotę i sfinalizować zakup.
- Częściową, podzielenie przechwycenia na jedno lub kilka żądań przechwycenia, do łącznej autoryzowanej kwoty.
Opis przechwytywania:
| Operacja | Typ operacji | Metoda Operacji & Endpoint | Opis Operacji |
|---|---|---|---|
| Card | Synchronous Call | POST version-id/{original-tx-id}/capture | Żąda przechwycenia środków finansowych (częściowej lub całkowitej kwoty) w związku z wcześniejszą autoryzacją. |
Żądanie przechwycenia:
| Lokalizacja | Element danych | Typ | Warunkowość | Opis |
|---|---|---|---|---|
| Path | original-tx-id | String | Mandatory | Original Transaction Id (identyfikator transakcji oryginalnej autoryzacji). |
| Request Header | Content-Type | String | Mandatory | application/json. |
| Request Header | authorization | String | Mandatory | Bearer Token. W oparciu o uwierzytelnianie OAuth2 wykonywane w kroku wstępnym. |
| Request Header | x-ibm-client-id | String | Mandatory | Token identyfikujący organizację klienta. Jest on dostarczany podczas procesu wdrażania i musi być używany w każdym połączeniu. |
| Request Body | merchant | Merchant | Mandatory | Obiekt definiujący merchanta. |
| Request Body.merchant | terminalId | Max10NumericText | – | Identyfikacja Terminala merchanta. |
| Request Body.merchant | channel | String | – | Kanał używany w transakcji. |
| Request Body.merchant | merchantTransactionId | String | Mandatory | Unikalny identyfikator transakcji z perspektywy merchanta. |
| Request Body | transaction | Transaction | Mandatory | Obiekt definiujący transakcję. |
| Request Body.transaction | transactionTimeStamp | ISODateTime | Mandatory | Transaction timestamp. |
| Request Body.transaction | description | String | Mandatory | Krótki opis transakcji. |
| Request Body.transaction | amount | Amount | Mandatory | Parametr z wartością i walutą transakcji. |
| Request Body.transaction.amount | value | Number (double) | Mandatory | Kwota w transakcji. |
| Request Body.transaction.amount | currency | Currency code | Mandatory | Waluta użyta w transakcji. Alpha3 |
| Request Body | originalTransaction | OriginalTransaction | Mandatory | Obiekt identyfikujący oryginalną transakcję. |
| Request Body.originalTransaction | id | String | Mandatory | Oryginalna identyfikacja transakcji. |
Tutaj można zobaczyć przykład żądania przechwytywania:
{
"merchant": {
"terminalId": {{TerminalID}},
"channel": "web",
"merchantTransactionId": "BO_Order Id: "
},
"transaction": {
"transactionTimestamp": "{{trxDatetime}}",
"description": "Transaction short description",
"amount": {
"value": 1,
"currency": "PLN"
},
"originalTransaction": {
"id": "{{originalTransactionId}}"
}
}
}Poniższa odpowiedź będzie zawierać identyfikator transakcji, którego można użyć do sprawdzenia statusu.
{
"merchant": {
"terminalId": "101776",
"merchantTransactionId": "BO_Order Id: ",
"merchantTransactionTimestamp": "2023-06-20T11:15:57.040Z"
},
"transactionTimestamp": "2023-06-20T11:16:14.988Z",
"amount": {
"value": "1",
"currency": "PLN"
},
"transactionID": "RW5vBMHj4RhQWFRc0GvS",
"execution": {
"startTime": "2023-06-20T11:15:57.206Z",
"endTime": "2023-06-20T11:16:15.100Z"
},
"paymentStatus": "Success",
"returnStatus": {
"statusCode": "000",
"statusMsg": "Success",
"statusDescription": "Success."
}
}Następnie, po przetworzeniu płatności, możesz sprawdzić status swojej transakcji, wykonując zapytanie GET .
Nagłówek HTTP autoryzacji jest ustawiony na Bearer Token, który został użyty w początkowym Checkout’cie.
Zapytanie URL:
https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/statusNagłówki żądań:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6I (...)
X-IBM-Client-Id: b4480347-9fc8-4790-b359-100a99c60ea3
Content-Type: application/jsonPomyślna odpowiedź techniczna składa się ze statusu HTTP-200 i wartości returnStatus.statusCode=”000″.
Oto kilka przykładów możliwych kodów wyników: