Hosted Payment Page (HPP)

Quick Start

The quick start for integration involves implementing the main API call that returns a web link that leads directly to the selection of payment methods.

This link will have three possible outcomes:

Successful processing "success"
Failed processing "failure"
The user canceled the operation "cancel"

In the case of "success," the merchant will always need to execute a confirmation call to capture the funds and close the order in the merchant’s sales system.

Step One: Generate Payment URL

POST /payment/api/v1/

The goal of this step is to obtain a request_id that allows the confirmation of the operation. To get this value, the process must end at the merchant’s URL prepared to capture the OK status. In terms of integration, this URL is called payload.redirect_after.success.

Sample request for a 300€ transaction:

Body
{
  "key": "key-value",
  "resource": "resource-value",
  "mode": "sha256",
  "nonce": "1234567890",
  "payload": {
    "amount": 30000,
    "currency": "EUR",
    "redirect_after": {
      "cancel": "http://httpbin.org/get?status=cancel",
      "success": "http://httpbin.org/get?status=success",
      "failure": "http://httpbin.org/get?status=failure"
    }
}

Parameter	Description
key	Merchant identifier.
mode	sha256 or sha512 depending on the hmac signature algorithm used.
resource	Merchant configuration resource identifier.
nonce	Unique identifier of the request, allows data duplication control. It is recommended to use a unix timestamp with maximum precision.
payload	Object with specific parameters for each request.
payload.amount	Amount in integer format and cents in the chosen currency. If the currency is Euro and you want to reflect 20.25€, multiply by 100 to get 2025.
payload.currency	ISO 4217 acronym for the currency. Example: EUR for Euro. See more at https://en.wikipedia.org/wiki/ISO_4217.
payload.redirect_after	Object with parameters that control the final redirection to the merchant and allows knowing the operation status to continue with the order closing process.
payload.redirect_after.success	The operation has been successfully completed, and payment confirmation can proceed. The URL for this parameter will have the request_id value concatenated in QueryString format. Example: redirect_after.success=http://httpbin.org/get?status=success final url=http://httpbin.org/get?status=success&request_id=abcdefgh1234
payload.redirect_after.failure	The operation encountered a processing error. The URL for this parameter will have the request_id value concatenated in QueryString format. Example: redirect_after.success=http://httpbin.org/get?status=failure final url=http://httpbin.org/get?status=failure&request_id=abcdefgh1234
payload.redirect_after.cancel	The user pressed the cancel or back button on the form. The URL for this parameter will have the request_id value concatenated in QueryString format. Example: redirect_after.success=http://httpbin.org/get?status=cancel final url=http://httpbin.org/get?status=cancel&request_id=abcdefgh1234

Sample response (truncated and simplified):

Body
{
    "type": "resource.status",
    "code": "0",
    "detail": "Successful payment request.",
    "payload": {
        "url": "https://sandbox.sipay.es/payment/api/v1/6269082af97d0740ef69ec66/fastpay",
        "payment_methods": {
            "card": {
                "url": "https://sandbox.sipay.es/payment/api/v1/6269082af97d0740ef69ec66/card",
                "supports_card_data": true,
                "supports_security_data": true,
                "supports_tokenization": true,
                "supports_recurring": true,
                "available_card_capturers": [
                    "gpay",
                    "apay"
                ],
                "supports_refund": true,
                "supports_direct_payment": false
            },
        }
    },
    "request_id": "6269082af97d0740ef69ec66",
    "uuid": "6269082af97d0740ef69ec66"
}

The url field should be used and sent to the browser so the consumer can start selecting the payment method.
The request_id value is essential to store as it will allow subsequent operations like:

You can find more information about the API at this link

Step Two: Confirm Operation

POST /payment/api/v1/{request_id}

Once we have captured the request_id value at the URL indicated in payload.redirect_after.success, we will program this API request to confirm the operation and capture the funds.

{
  "key": "key-value",
  "resource": "resource-value",
  "mode": "sha256",
  "nonce": "1234567890",
  "payload": {}
}

Parameter	Description
key	Merchant identifier.
mode	sha256 or sha512 depending on the hmac signature algorithm used.
resource	Merchant configuration resource identifier.
nonce	Unique identifier of the request, allows data duplication control. It is recommended to use a unix timestamp with maximum precision.
payload	Object with specific parameters for each request. In this case, it will be empty as this is the quick start example and no further customization is needed.

Prototype response:

{
    "type": "resource.status",
    "code": "0",
    "detail": "Operation confirmed successfully",
    "payload": {
					...
        }
    },
    "request_id": "6242d085b19538c1ea4ccff1",
    "uuid": "6242d085b19538c1ea4ccff1"
}

The code 0 indicates the operation has been successfully completed.

Full response of a successful card payment
{
  "type": "resource.status",
  "code": "0",
  "detail": "Operation confirmed successfully",
  "payload": {
    "extra": {
      "code": "0",
      "amount": "15000",
      "currency": "EUR",
      "order": "92b2e95848fe403881973973438c44d9",
      "card_trade": "undefined",
      "card_type": "undefined",
      "masked_card": "6712 00** ****0205",
      "reconciliation": "",
      "transaction_id": "000027346264324805241",
      "cof_id": "009034153465",
      "authorizator": "BANCO SANTANDER, S.A.",
      "approval": "293950",
      "card_country": "undefined",
      "card_brand": "MAESTRO",
      "expiration": "1122"
    }
  },
  "request_id": "6242d8b356d30070b6798d3f",
  "uuid": "6242d8b356d30070b6798d3f"
}

caution

If you confirm an already completed payment two or more times, you will receive this message. With the request_id, you can make a query to view the result.

response of an already confirmed payment
{
  "type": "resource.status",
  "code": "-1",
  "detail": "An error happened upon confirmation",
  "payload": {
    "extra": {
      "operation_status": "already_confirmed",
      "payload": {}
    }
  },
  "request_id": "6242d79756d30070b6798d2c",
  "uuid": "6242d79756d30070b6798d2c"
}

If we execute the API call:

GET /payment/api/v1/6242d79756d30070b6798d2c?key=key-value&resource=resource-value&mode=sha256&nonce=1234567890

we would get the following response:

operation query
{
  "type": "resource.status",
  "code": "0",
  "detail": "Operation status retrieved successfully",
  "payload": {
    "code": 0,
    "amount": 15000,
    "order": "92b2e95848fe403881973973438c44d9",
    "currency": "EUR",
    "payment_method_name": "not_started",
    "cart": {
      "items": [
        {
          "sku": "MYSKU",
          "tax": "11",
          "name": "item name",
          "quantity": "10",
          "amount": 10,
          "image": "https://assets.codepen.io/8146504/8E370E15-031D-491D-A388-C35101A271FC.jpeg"
        }
      ]
    },
    "events": {
      "create_session": [
        {
          "triggered_at": "2022-10-31T16:30:46Z",
          "extra": {}
        }
      ]
    },
    "extra": {}
  },
  "request_id": "6242d79756d30070b6798d2c",
  "uuid": "635fea26198fd062244ec736"
}

You can find more information about the API at this link

Quick Start​

Step One: Generate Payment URL​

Step Two: Confirm Operation​

Quick Start

Step One: Generate Payment URL

Step Two: Confirm Operation