Skip to main content

🇬🇪 Georgia v0.8 - Payment initiation request

POST https://open-banking-api.paysera.com/xs2a/georgia/0.8/v1/{payment-service}/{payment-product}

This method is used to initiate a payment at the ASPSP.

Variants of payment initiation requests​

This method to initiate a payment initiation at the ASPSP can be sent with a JSON body.

There are the following payment products:

  • Payment products with payment information in JSON format:
    • aspsp
    • domestic
    • foreign

Furthermore the request body depends on the payment-service:

  • payments: A single payment initiation request.
  • bulk-payments: A collection of several payment initiation requests.
  • periodic-payments: Create a standing order initiation resource for recurrent i.e. periodic payments addressable under {paymentId} with all data relevant for the corresponding payment product and the execution of the standing order contained in a JSON body.

This is the first step in the API to initiate the related recurring/periodic payment.

Single and mulitilevel SCA Processes​

The payment initiation requests are independent from the need of one or multilevel SCA processing, i.e. independent from the number of authorisations needed for the execution of payments.

But the response messages are specific to either one SCA processing or multilevel SCA processing.

For payment initiation with multilevel SCA, this specification requires an explicit start of the authorisation, i.e. links directly associated with SCA processing like 'scaRedirect' or 'scaOAuth' cannot be contained in the response message of a Payment Initation Request for a payment, where multiple authorisations are needed. Also if any data is needed for the next action, like selecting an SCA method is not supported in the response, since all starts of the multiple authorisations are fully equal. In these cases, first an authorisation sub-resource has to be generated following the 'startAuthorisation' link.

Authorization​

This endpoint requires mTLS (Mutual TLS) authentication using a valid QWAC certificate.

Requirements:

  • Valid QWAC certificate issued by a qualified trust service provider (QTSP)
  • Certificate must be registered with Paysera
  • Certificate organization identifier must match your TPP registration in the EBA register

Example (cURL):

curl https://open-banking-api.paysera.com/xs2a/georgia/0.8/v1/endpoint \
  --cert qwac-cert.pem \
  --key qwac-key.pem \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: $(uuidgen)"

For detailed authentication guide, see Authentication.

Parameters​

Path Parameters​

NameTypeRequiredDescription
payment-servicestring✓Payment service:

Possible values are:

  • payments
  • bulk-payments
  • periodic-payments | | payment-product | string | ✓ | The addressed payment product endpoint, e.g. for SEPA Credit Transfers (SCT). The ASPSP will publish which of the payment products/endpoints will be supported.

The following payment products are supported:

  • aspsp
  • domestic
  • foreign |

Request Body​

JSON request body for a payment inition request message.

There are the following payment-products supported:

  • "aspsp" with JSON-Body
  • "domestic" with JSON-Body
  • "foreign" with JSON-Body

There are the following payment-services supported:

  • "payments"
  • "periodic-payments"
  • "bulk-payments"

All optional, conditional and predefined but not yet used fields are defined.

Errors​

This endpoint may return the following errors:

400 - Bad Request​

The request could not be understood by the server due to malformed syntax or invalid parameters.

Common error codes:

  • FORMAT_ERROR - Invalid request format or syntax
  • PARAMETER_NOT_CONSISTENT - Request parameters are inconsistent with each other
  • PARAMETER_NOT_SUPPORTED - Request contains unsupported parameters
  • SERVICE_INVALID - The addressed service is not valid for the addressed resources
  • RESOURCE_UNKNOWN - The addressed resource is unknown relative to the TPP
  • RESOURCE_EXPIRED - The addressed resource has expired
  • RESOURCE_BLOCKED - The addressed resource is blocked
  • TIMESTAMP_INVALID - The provided timestamp is invalid or malformed
  • PERIOD_INVALID - The provided time period is invalid
  • SCA_METHOD_UNKNOWN - The requested SCA method is not supported
  • SCA_INVALID - The SCA authentication data is invalid
  • CONSENT_UNKNOWN - The consent ID is unknown or invalid
  • CONSENT_INVALID - The consent is invalid or cannot be used
  • PAYMENT_FAILED - The payment initiation has failed
  • EXECUTION_DATE_INVALID - The execution date is invalid (e.g., in the past or too far in the future)
  • REQUIRED_KYC_MISSING - Required KYC information is missing
  • SESSIONS_NOT_SUPPORTED - Sessions are not supported by this ASPSP
  • ACCESS_EXCEEDED - The access frequency limit has been exceeded
  • REQUESTED_FORMATS_INVALID - The requested formats are not supported
  • BENEFICIARY_WHITELISTING_REQUIRED - This operation requires beneficiary whitelisting

Example response:

{
  
  "title": "Bad Request",
  "detail": "Invalid request format or syntax",
  "code": "FORMAT_ERROR"
}

401 - Unauthorized​

Certificate authentication failed or is missing.

Common error codes:

  • CERTIFICATE_INVALID - The TPP certificate is not valid
  • CERTIFICATE_EXPIRED - The TPP certificate has expired
  • CERTIFICATE_BLOCKED - The TPP certificate has been blocked by the ASPSP
  • CERTIFICATE_REVOKED - The TPP certificate has been revoked
  • CERTIFICATE_MISSING - The TPP certificate is missing in the request
  • ROLE_INVALID - The TPP certificate does not have the required role (PIS, AIS, PIIS, etc.)
  • SIGNATURE_INVALID - The request signature is invalid or verification failed
  • SIGNATURE_MISSING - The required signature is missing from the request
  • CORPORATE_ID_INVALID - The corporate ID in the certificate does not match the registration
  • PSU_CREDENTIALS_INVALID - The PSU credentials provided are invalid
  • CONSENT_INVALID - The consent token is invalid or has been revoked

Example response:

{
  
  "title": "Unauthorized",
  "detail": "The TPP certificate is not valid",
  "code": "CERTIFICATE_INVALID"
}

403 - Forbidden​

The TPP does not have the necessary permissions or the resource access is forbidden.

Common error codes:

  • CONSENT_UNKNOWN - The consent ID is unknown or invalid
  • CONSENT_EXPIRED - The consent has expired and can no longer be used
  • CONSENT_INVALID - The consent is invalid for this operation
  • SERVICE_BLOCKED - The TPP has been blocked from accessing this service
  • RESOURCE_UNKNOWN - The requested resource is unknown or does not exist
  • RESOURCE_EXPIRED - The requested resource has expired
  • PRODUCT_INVALID - The payment product is not supported by the ASPSP
  • PRODUCT_UNKNOWN - The addressed payment product is unknown
  • TOKEN_UNKNOWN - The OAuth2 token is unknown or invalid
  • TOKEN_INVALID - The OAuth2 token is invalid or has been revoked
  • TOKEN_EXPIRED - The OAuth2 token has expired
  • ACCESS_EXCEEDED - The number of accesses has exceeded the limit

Example response:

{
  
  "title": "Forbidden",
  "detail": "The consent ID is unknown or invalid",
  "code": "CONSENT_UNKNOWN"
}

404 - Not Found​

The requested resource could not be found.

Common error codes:

  • RESOURCE_UNKNOWN - The addressed resource is not found or does not exist
  • PRODUCT_UNKNOWN - The addressed payment product is not supported or unknown

Example response:

{
  
  "title": "Not Found",
  "detail": "The addressed resource is not found or does not exist",
  "code": "RESOURCE_UNKNOWN"
}

405 - Method Not Allowed​

The HTTP method used is not allowed for this endpoint.

Common error codes:

  • SERVICE_INVALID - The HTTP method is not supported for this service

Example response:

{
  
  "title": "Method Not Allowed",
  "detail": "The HTTP method is not supported for this service",
  "code": "SERVICE_INVALID"
}

406 - Not Acceptable​

The Accept header in the request is not supported. The API requires application/json.

Common error codes:

  • REQUESTED_FORMATS_INVALID - None of the requested formats are supported

Example response:

{
  
  "title": "Not Acceptable",
  "detail": "None of the requested formats are supported",
  "code": "REQUESTED_FORMATS_INVALID"
}

408 - Request Timeout​

The request took too long to process and timed out. This may occur if the PSU takes too long to authorize or if external systems are slow to respond.

Example response:

{
  
  "title": "Request Timeout",
  "detail": "The request took too long to process and timed out. This may occur if the PSU takes too long to authorize or if external systems are slow to respond."
}

409 - Conflict​

The request conflicts with the current state of the resource.

Common error codes:

  • STATUS_INVALID - The resource is in a status that does not allow this operation (e.g., trying to cancel an already executed payment)
  • CONSENT_CONFLICT - The consent request conflicts with an existing consent
  • ACCESS_EXCEEDED - The access has been attempted too many times

Example response:

{
  
  "title": "Conflict",
  "detail": "The resource is in a status that does not allow this operation (e.g., trying to cancel an already executed payment)",
  "code": "STATUS_INVALID"
}

415 - Unsupported Media Type​

The Content-Type header in the request is not supported. The API requires application/json.

Example response:

{
  
  "title": "Unsupported Media Type",
  "detail": "The Content-Type header in the request is not supported. The API requires `application/json`."
}

429 - Too Many Requests​

The TPP has exceeded the rate limit. Paysera Open Banking API applies the following rate limits:

10 requests per second - Maximum request rate 1000 requests per hour - Hourly quota 20 concurrent requests - Maximum parallel requests

Common error codes:

  • ACCESS_EXCEEDED - The TPP has sent too many requests in a given timeframe

Example response:

{
  
  "title": "Too Many Requests",
  "detail": "The TPP has sent too many requests in a given timeframe",
  "code": "ACCESS_EXCEEDED"
}

500 - Internal Server Error​

An unexpected error occurred on the server side. This indicates a problem with the ASPSP's system. Please try again later or contact Paysera support if the issue persists.

Example response:

{
  
  "title": "Internal Server Error",
  "detail": "An unexpected error occurred on the server side. This indicates a problem with the ASPSP's system. Please try again later or contact Paysera support if the issue persists."
}

503 - Service Unavailable​

The service is temporarily unavailable due to maintenance or overload. The request can be retried after a short delay. Check the Retry-After header if present.

Example response:

{
  
  "title": "Service Unavailable",
  "detail": "The service is temporarily unavailable due to maintenance or overload. The request can be retried after a short delay. Check the `Retry-After` header if present."
}

Example​

Request​

POST https://open-banking-api.paysera.com/xs2a/georgia/0.8/v1/{payment-service}/{payment-product}
Content-Type: application/json
# Certificate authentication via mTLS, ext="body_hash=BODY_HASH"
{
  "instructedAmount": {
    "currency": "GEL",
    "amount": "123.50"
  },
  "debtorAccount": {
    "iban": "GE00BG0000000000000000"
  },
  "creditorName": "Merchant123",
  "creditorAccount": {
    "iban": "GE00BG0000000000000001"
  },
  "remittanceInformationUnstructured": "Ref Number Merchant"

}

Response​

{
  "transactionStatus": "RCVD",
  "paymentId": "1234-wertiq-983",
  "_links": {
    "scaRedirect": {
      "href": "https://www.testbank.com/asdfasdfasdf"
    },
    "self": {
      "href": "/v1/payments/sepa-credit-transfers/1234-wertiq-983"
    },
    "status": {
      "href": "/v1/payments/1234-wertiq-983/status"
    },
    "scaStatus": {
      "href": "/v1/payments/1234-wertiq-983/authorisations/123auth456"
    }
  }

}

AUTHORIZATION: HTTP

REQUEST

Base URL
https://open-banking-api.paysera.com
Body REQUIRED
{
  "instructedAmount": {
    "currency": "GEL",
    "amount": "123.50"
  },
  "debtorAccount": {
    "iban": "GE00BG0000000000000000"
  },
  "creditorName": "Merchant123",
  "creditorAccount": {
    "iban": "GE00BG0000000000000001"
  },
  "remittanceInformationUnstructured": "Ref Number Merchant"
}

RESPONSE

CREATED
{
  "transactionStatus": "RCVD",
  "paymentId": "1234-wertiq-983",
  "_links": {
    "scaRedirect": {
      "href": "https://www.testbank.com/asdfasdfasdf"
    },
    "self": {
      "href": "/psd2/v1/payments/sepa-credit-transfers/1234-wertiq-983"
    },
    "status": {
      "href": "/psd2/v1/payments/1234-wertiq-983/status"
    },
    "scaStatus": {
      "href": "/psd2/v1/payments/1234-wertiq-983/authorisations/123auth456"
    }
  }
}