SagaPay API Architecture

This guide covers the key aspects of integrating with SagaPay APIs.

Making API Calls

Example API Request

Here’s a quick example of initiating a payment:

$
curl -d '{
>
          "orderId": "o_RelSnor1A6gqgKzZxrbM7",
>
          "paymentMethod": "CARD"
>
         }' \
>
     -H 'Content-Type: application/json' \
>
     -H 'API-KEY: YOUR_API_KEY' \
>
     -H 'API-SECRET: YOUR_API_SECRET' \
>
     -H 'MERCHANT-ID: MERCHANT_ID' \
>
     YOUR_API_URL/payments

Headers

Headers are key-value pairs that convey metadata, authentication details, and other information crucial for processing requests and responses.

Apart from the API_URL, you must provide the API-KEY and API-SECRET headers for all calls. The MERCHANT-ID is also significant for all partners offering a seamless payment solution to their merchants.

Data Format

SagaPay currently offers JSON format as the only request/response markup. If you require other formats, please reach out to us at support@sagapay.no

Understanding API Response

Here is a short example of a response:

1
{
2
    "status" : "SUCCESS",
3
    "data"  : {...},
4
    "message": "Message related to the API call"
5
}

Handle the response: All API calls will return JSON, with containing the status and data properties.

The API response includes a status property indicating success or failure. Additional details like message might be included.

The message for the status will be as follows:

• SUCCESS: The request was successful.
• ERROR: The request failed.

Errors

Here is an example of an error response:

1
{
2
    "status": "ERROR",
3
    "message": "An Error occured here is the description"
4
}

For errors, the status property will contain ERROR and the message property will display a message describing the error.

HTTP Status Handling

HTTP statuses adhere to the RFC 9110 standard. A 2XX HTTP status indicates a successful response, but you should also check the status attribute of the API response. If it is ERROR, refer to the message attribute for details on the error and its cause.

Below is a table of the most commonly received HTTP status codes from the SagaPay APIs. For a complete list of HTTP status codes, please refer to the RFC 9110 standard.

Go Live with Your Integration

To go live:

Base URLs

Best Practices