Payment
Overview
Base URLs: https://api.rumbapay.online/v1/
Data Format: JSON
HTTP Methods: POST, PUT, GET
Initialize payment
When creating a payment using the method https://api.rumbapay.online/v1/payment you must inspect the challenge.challenge_type field to determine the appropriate flow.
Method: HTTP POST
URL: https://api.rumbapay.online/v1/payment
Request Body Type HPP:
{
"reference": "{{$guid}}",// required
"currency": "PLN",// required
"amount": "12.23", // required
"description": "descripion", // optional
"customer": {
"identifier": "12345", // required, unique value from the system of the merchant
"email": "user@example.com", // conditional
"phone": "333333333", // conditional
"first_name": "Jan", // conditional
"last_name": "Kowalski", // conditional
"middle_name": "Marian", // optional
"country": "PL", // conditional
"state_code": "PL-14", // conditional
"city": "Warsaw", // conditional
"address": "Krakowskie Przedmieście 1", // conditional
"zip_code": "00-001", // conditional
"itn": "X1234567890", // optional
"birthday": "1980-05-15", // optional
"ip": "192.168.0.1", // conditional
"gender": "male" // optional
},
"widget": {
"method": "blik", // required
"locale": "pl" // optional
},
"redirect_url": "https://merchant.domain/pending", // optional
"callback_url": "https://merchant.domain/callback", // conditional
"cancel_url": "https://merchant.domain/cancel", // optional
"extra": // conditional, any field which may be needed for transaction routing and integration
[{"key_1":"value"},{"key_2":"value"},{"key_3":"value"},{"key_4":"value"}]
}Request Body Type H2H:
{
"method": "blik", // required
"mode": "initial", // required, only "initial" for this method
"reference": "{{$guid}}", // required
"currency": "PLN", // required
"amount": 25.01, // required
"description": "My order", // conditional
"customer": { // required
"identifier": "12345", // required, unique value from the system of the merchant
"email": "user@example.com", // conditional
"phone": "333333333", // conditional
"first_name": "Jan", // conditional
"last_name": "Kowalski", // conditional
"middle_name": "Marian", // optional
"country": "PL", // conditional
"state_code": "PL-14", // conditional
"city": "Warsaw", // optional
"address": "Krakowskie Przedmieście 1", // conditional
"zip_code": "00-001", // conditional
"itn": "X1234567890", // optional
"birthday": "1980-05-15", // optional
"ip": "192.168.0.1", // conditional
"gender": "male" // optional
},
"redirect_url": "https://merchant.domain/customer_pending_page", // conditional
"callback_url": "https://merchant.domain/callback", // conditional
"extra": // conditional, any field which may be needed for transaction routing and integration
[{"key_1":"value"},{"key_2":"value"},{"key_3":"value"},{"key_4":"value"}]
}Response (Success):
Response - 200 OK
First, you should check error_code field of response.
If error_code field is not equals to 0 - transaction is Failed.
Second, you should check status field.
The status field will always be set to created if there are no errors.
Make check request or wait for a callback to get final transaction status.
Challenge type: redirect
{
"error_code": 0,
"error_reason": "",
"identifier": "PM00000000CML8A",
"request_id": "65578e53-ee92-47f4-9202-c4c5c9572449",
"reference": "ref-1617300503",
"status": "pending",
"type": "payment",
"method": "blik",
"mode": "initial",
"currency": "PLN",
"amount": "25.01",
"challenge": {
"challenge_type": "redirect",
"challenge_redirect": {
"url": "https://some.url.com/65578e53-ee92-47f4-9202-c4c5c9572449""
}
},
"timestamp": "2024-04-01T18:08:24Z"
}If you get challenge.challenge_type with value redirect then you should redirect your Customer to the URL in the field challenge.challenge_redirect.url.
After the Customer successfully completes the challenge flow on our partner's page, they will be automatically redirected to the URL specified in the redirect_url field of your request.
Response - 400 Bad request
{
"error_code": 30,
"error_reason": "Invalid params",
"request_id": "36b61e02-fab7-4fb6-81b7-6e12f0acda16",
"error_fields": [
{
"field": "reference",
"message": "reference is a required field"
}
],
"timestamp": "2024-02-09T10:48:09Z"
}If incorrect values are provided for widget.method or currency, you may receive the following response:
{
"error_code": 273,
"error_message": "Invalid adapter route configuration"
}Callback
We send a callback notification to the URL you passed in the transaction request in the callback_url field on every completed transaction.
We strongly recommend validating the callback signature to avoid suspicious activity. Follow the signature docs to prepare callback verification.
Callback flow
The callback flow follows these steps:
Rumbapay processes the payment request
When the payment status changes to a terminal state, Rumbapay sends an HTTP POST request to your callback URL
Your server should process the callback, validate the signature, and update your system
Your server should respond with HTTP 200 OK to acknowledge receipt
Example
{
"identifier": "PM00000000FONI1",
"creation_date": "2024-02-09T13:12:10.886803",
"request_id": "ad8f2092-fe60-458c-9caa-4106006a51a3",
"reference": "order-00001",
"method": "blik",
"type": "payment",
"mode": "initial",
"status": "success",
"status_date": "2024-02-09T13:12:18.395695",
"amount": "25.01",
"currency": "PLN",
"billing_amount": "25.01",
"billing_currency": "PLN",
"fee_amount": "3.75",
"fee_currency": "PLN",
"customer": {
"identifier": "12345",
"email": "user@example.com",
"phone": "333333333",
"first_name": "Jan",
"last_name": "Kowalski",
"middle_name": "Marian",
"country": "PL",
"state_code": "PL-14",
"city": "Warsaw",
"address": "Krakowskie Przedmieście 1",
"zip_code": "00-001",
"itn": "X1234567890",
"birthday": "1980-05-15",
"ip": "192.168.0.1",
"gender": "male"
},
"error_code": 0,
"error_reason": "",
"timestamp": "2024-02-09T13:12:19.440901"
}Check Payment Status
Method: HTTP GET
URL: https://api.rumbapay.online/v1/transaction/{request_id}
Response (Success):
{
"error_code": 0,
"error_reason": "",
"identifier": "PM00000000FONI1",
"request_id": "8f0b50db-7ede-4edb-b36c-8b5cffdf9310",
"reference": "order-00001",
"method": "blik",
"type": "payment",
"mode": "initial",
"currency": "PLN",
"amount": "25.01",
"status": "success",
"timestamp": "2024-04-01T18:08:24Z",
"status_date": "2024-04-01T18:07:03Z"
}Response (Not Found):
Transaction not found
{
"error_code": 101,
"error_reason": "Transaction not found",
"request_id": "0a799552-95a4-4120-b71a-54e8c20b9b31",
"timestamp": "2024-04-10T21:31:15Z"
}Last updated