Menu

Płatności cykliczne

Twoi klienci mają możliwość korzystania z płatności cyklicznych za pomocą kart Visa i Mastercard. Celem tej operacji jest umożliwienie sprzedawcom pobierania opłat za usługi cykliczne.

Tego typu płatności są powszechnie stosowane w połączeniu z subskrypcjami usług lub towarów, gdy klient kupuje usługę subskrypcji, która może być regularnie obciążana wiele razy po początkowej płatności.

Istnieją dwa rodzaje płatności cyklicznych:

  • z harmonogramem wstępnym
  • bez wstępnego harmonogramu.

Jak to działa

W pierwszym etapie posiadacz karty żąda płatności jako początkowej płatności cyklicznej i upoważnia sprzedawcę do dokonywania przyszłych obciążeń (kolejnych płatności cyklicznych) zgodnie z usługą.

Krok 1: Płatność początkowa

Działanie 1: Utworzenie zamówienia
Działanie 2: Wygenerowanie transakcji
Działanie 3: Można wykonać polecenie Uzyskaj Status

Jest to kluczowe dla posiadacza karty, aby zarejestrować początkową płatność cykliczną u sprzedawcy. Aby to osiągnąć, należy wykonać trzy czynności opisane poniżej.

Działanie 1: Utworzenie zamówienia

Proces ten rozpoczyna się po uruchomieniu strony i utworzeniu zamówienia , dodając następujące powtarzające się elementy do istniejącej treści zamówienia.

Element danychTypStanOpis
recurringTransactionInputRecurringTransactionWymaganeObiekt definiujący żądanie transakcji cyklicznej. Występuje tylko w przypadku transakcji cyklicznych.
validityDateisoDateTimeWymaganeData ważności transakcji cyklicznej.
amountQualifierCiągWymaganeKwalifikator kwoty transakcji cyklicznej.
opisCiągOpcjonalnieOpis transakcji cyklicznej.
harmonogramHarmonogramOpcjonalnieHarmonogram transakcji cyklicznych.
initialDateisoDateTimeOpcjonalnieData rozpoczęcia transakcji cyklicznej Godzina.
finalDateisoDateTimeOpcjonalnieData zakończenia transakcji cyklicznej Godzina.
interwałIntervalTypeOpcjonalnieCzęstotliwość transakcji cyklicznych.
Możliwe wartości to (
„DAILY”,
„WEEKLY”,
„BIWEEKLY”,
„MONTHLY”,
„QUARTERLY”,
„SEMIANNUAL”,
„ANNUAL” ).

Pamiętaj, że w tym przypadku na liście transakcja.paymentMethod powinieneś uwzględnić tylko „KARTĘ”.

Przykład żądania:

Uruchom w Postmanie

Adres URL żądania:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments

Nagłówki żądań:

Autorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6I (...)
X-IBM-Client-Id: b4480347-9fc8-4790-b359-100a99c60ea3
Content-Type: application/json
{
    "merchant": {
        "terminalId": 24,
        "channel": "web",
        "merchantTransactionId": "Order Id: uhk476ae77",
        "transactionDescription": "Recurring transaction",
        "shopURL": "https://mytest.e-shop.pl/"
    },
    "transaction": {
        "transactionTimestamp": "2023-06-09T08:38:20.680Z",
        "description": "transaction statement description",
        "moto": false,
        "paymentType": "AUTH",
        "amount": {
            "value": 50.5,
            "currency": "PLN"
        },
        "paymentMethod": [
            "CARD"
        ]
    },
    "recurringTransaction": {
        "validityDate": "2023-12-08T09:38:20.680Z",
        "amountQualifier": "DEFAULT"
    }
}
Działanie 2: Wygenerowanie transakcji

Poniższe żądanie wymaga nagłówka autoryzacji z podpisem transakcji zwróconym z operacji realizacji zakupu.

W tym żądaniu token okaziciela jest zastępowany przez transactionSignature odpowiedzi kasy.

Przykład żądania:

Uruchom w Postmanie

Adres URL żądania:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/card/purchase

Nagłówki żądań:

Authorisation: Digest {transactionSignature}
X-IBM-Client-Id: b4480347-9fc8-4790-b359-100a99c60ea3
Content-Type: application/json
{
    "cardInfo": {
        "PAN": "5204740000001002",
        "secureCode": "100",
        "validationDate": "2025-12-31T00:00:00.000Z",
        "cardholderName": "Jane Smith",
        "createToken": false
    }
}

Powinieneś otrzymać pomyślną odpowiedź techniczną, która zawiera status HTTP-200 i returnStatus.statusCode równy „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ń.

  • Sukces: Zakup został pomyślnie przetworzony, a klient został obciążony.
  • Odrzucono: Zakup został odrzucony
  • W toku: Ostateczny wynik zakupu 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ć.
  • Częściowy: Zakup został częściowo zaakceptowany, ale wymaga wykonania dodatkowych czynności (np. uwierzytelnienia 3D Secure ). Element actionResponse zawiera instrukcje dotyczące dalszego postępowania.

Odpowiedź powinna również zawierać recurringTransaction.status, który wskazuje, czy konfiguracja cykliczna została pomyślnie ustanowiona. Status ten dostarcza informacji na temat prawidłowej konfiguracji konfiguracji cyklicznej.

Działanie 3: Można wykonać polecenie Uzyskaj Status

Po przetworzeniu płatności możesz sprawdzić status swojej transakcji, wysyłając żądanie GET.

Nagłówek HTTP autoryzacji jest ustawiony na token okaziciela, tak jak był używany podczas początkowej realizacji transakcji.

GET {transactionID}/status
Uruchom w Postmanie

Adres URL żądania:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/status

Nagłówki żądań:

Authorization: ‘Bearer <AuthToken>’
X-IBM-Client-Id: ‘<ClientId>’
Content-Type: application/json

Pomyślna odpowiedź techniczna składa się ze statusu HTTP-200 i returnStatus.statusCode=”000„.

Oto kilka przykładów możliwych kodów wyników:

Result CodestatusMsgDescriptionAction
HTTP-200SuccessSuccess responseN/A
HTTP-400Bad RequestThe JSON payload is not matching the API definition or some mandatory HTTP headers are missing.Please check in API Market for the correct syntax.
HTTP-401UnauthorizedOn the Authorization, Bearer token is invalid/expired or not associated with the Terminal used.Please check in SIBS Backoffice under the Credentials if the token is valid and create a new one if needed.
HTTP-403ForbiddenThe ClientID set on the X-IBM-Client-Id HTTP header is not valid or does not possess a valid subscription to the API.Please check in SIBS Backoffice under the SPG APP 2.0 if the ClientID is correct. If the problem persists contact SIBS Gateway support for a ClientID reset.
HTTP-405Method Not AllowedThe HTTP Method used is not matching any of the API definitions available.Please check in API Market for the correct HTTP Method.
HTTP-429Too Many Requests
The API calls rate limit has been exceeded.Please check in API Market for information on the rate limits that apply to the API.
HTTP-500Internal Server ErrorThe API call has failed… and its most likely on our side.You should retry the operation, and if the problem persists contact SIBS Gateway support for assistance.
HTTP-503Service UnavailableThe API call is not currently available. Usually we are always on, but short availability issues may occur during scheduled maintenance.You should wait and try again later.

Krok 2: Płatność cykliczna

Działanie 1: Wygeneruj kolejne transakcje
Działanie 2: Wykonaj polecenie Uzyskaj status
Działanie 1: Wygeneruj kolejne transakcje

Płatność cykliczna służy do przetwarzania kolejnych płatności w ramach wcześniej autoryzowanej początkowej płatności cyklicznej.

Żądanie jest realizowane poprzez odniesienie do identyfikatora transakcji poprzedniej płatności początkowej i wysłanie bezpiecznego żądania POST przez HTTPS do punktu końcowego /payments/{transactionID}/recurring.

POST https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/recurring

Przykład żądania:

Uruchom w Postmanie

Adres URL żądania:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/recurring

Nagłówki żądań:

Autorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6I (...)
X-IBM-Client-Id: b4480347-9fc8-4790-b359-100a99c60ea3 Content-Type: application/json
Content-Type: application/json
{
    "merchant": {
        "terminalId": 24,
        "channel": "web",
        "merchantTransactionId": "BO_Order Id: sar5f6ry2i"
    },
    "transaction": {
        "transactionTimestamp": "2023-06-09T07:49:45.348Z",
        "description": "Transaction short description",
        "amount": {
            "value": 50.5,
            "currency": "PLN"
        },
        "originalTransaction": {
            "id": ""
        }
    }
}
Działanie 2: Wykonaj polecenie Uzyskaj status

Po przetworzeniu płatności możesz sprawdzić status swojej transakcji, wysyłając żądanie GET.

Nagłówek HTTP autoryzacji jest ustawiony na token okaziciela, tak jak był używany podczas początkowej realizacji transakcji.

GET {transactionID}/status
Uruchom w Postmanie

Adres URL żądania:

https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/status

Nagłówki żądań:

Authorization: ‘Bearer <AuthToken>’
X-IBM-Client-Id: ‘<ClientId>’
Content-Type: application/json

Pomyślna odpowiedź techniczna składa się ze statusu HTTP-200 i returnStatus.statusCode=”000„.

Oto kilka przykładów możliwych kodów wyników:

Result CodestatusMsgDescriptionAction
HTTP-200SuccessSuccess responseN/A
HTTP-400Bad RequestThe JSON payload is not matching the API definition or some mandatory HTTP headers are missing.Please check in API Market for the correct syntax.
HTTP-401UnauthorizedOn the Authorization, Bearer token is invalid/expired or not associated with the Terminal used.Please check in SIBS Backoffice under the Credentials if the token is valid and create a new one if needed.
HTTP-403ForbiddenThe ClientID set on the X-IBM-Client-Id HTTP header is not valid or does not possess a valid subscription to the API.Please check in SIBS Backoffice under the SPG APP 2.0 if the ClientID is correct. If the problem persists contact SIBS Gateway support for a ClientID reset.
HTTP-405Method Not AllowedThe HTTP Method used is not matching any of the API definitions available.Please check in API Market for the correct HTTP Method.
HTTP-429Too Many Requests
The API calls rate limit has been exceeded.Please check in API Market for information on the rate limits that apply to the API.
HTTP-500Internal Server ErrorThe API call has failed… and its most likely on our side.You should retry the operation, and if the problem persists contact SIBS Gateway support for assistance.
HTTP-503Service UnavailableThe API call is not currently available. Usually we are always on, but short availability issues may occur during scheduled maintenance.You should wait and try again later.

On this page: