The Payment Execution API allows third party payment initiators (PISPs) to execute payments on behalf of a Santander bank's client.
In its Sandbox version, the API is configurated to only accept some specific access_tokens. These access_tokens allow us to univocally identify a Banco Santander client, a partner TPP and the associated scopes.
The available access_tokens for Sandbox environment are the following:
1. ce4b1dc1-0dc8-43b1-ac01-8dd0c5d09118
2. 1bf92e18-0689-46f5-932f-9253d577f1d6
3. 8f6ff69f-195e-4cbb-993a-0d20fc7ffdf2
4. 174b2b76-ddee-47a0-a05f-26c1bee732df
In the Live (real) version of the API, each access_token should be obtained through the authorization process.
production
https://apis-sandbox.bancosantander.es/canales-digitales/sb
Paths
/
post /
clientIdHeader
X-IBM-Client-Id
(apiKey located in header)
This parameter is the ID that identifies the TPP/PISP that has previously registered in the API Portal.
Authorization
Required in header
string
The API is protected by the authorization header. The TPP must indicate the access_token obtained after completing the OAuth 2.0 authorization process of the payment initiation.
idempotent_key
Optional in header
string
Idempotency key associated to the operation. It allows the PISP to retry an operation if there has been a connection failure or timeout, guaranteeing that the side effects will occurr only once. It must be defined according to RFC4122 (header parameter). The size must be less than 40 characters and must expire after 24 hours. If the same idempotency key is received by the same PISP within 24 hours, a new operation will not be created and an error code of 409 will be returned.
interaction_id
Optional in header
string
Unique ID of the request, for monitoring purposes by the third party (Optional). Please use the Interaction-ID specified during initiation as other identifiers will be ignored.
payment_body
Required in body
object
The information required to execute the API. It contains the signature token (SOS-JWT-TOKEN) obtained from the Payment Initiation API response.
Content-Type
Optional in header
string
application/json
Accept
Optional in header
string
application/json
200
200 OK
400
400 Bad request
401
401 Unauthorized request
403
403 Access denied
404
404 Resource not found
500
500 Internal error
Example Request
Example Response
POST https://apis-sandbox.bancosantander.es/canales-digitales/sb/v2/payment-execution/
Try this operation
Definitions
The custom-error object allows customization of the error messages that can be shown during the API execution.
{
"properties": {
"developerMessage": {
"type": "string",
"description": "Message that is sent to the developer.",
"example": "ClientId in signature token differs from the ClientId associated to the access token"
},
"userMessage": {
"type": "string",
"description": "Message that is sent to the user.",
"example": "The operation can not be reached."
},
"status": {
"type": "string",
"description": "HTTP Status of the error.",
"example": "401"
},
"moreInfo": {
"type": "string",
"description": "More information related to the errors.",
"example": "https:\/\/developer.bancosantander.es\/api\/errors\/GOIT_001"
},
"code": {
"type": "string",
"description": "Unique identifier for the error code.",
"example": "GOIT_001"
}
},
"additionalProperties": false,
"required": [
"code",
"userMessage",
"moreInfo",
"status",
"developerMessage"
]
}
This object contains the information associated with the transfer fee.
{
"properties": {
"spending_policy": {
"type": "string",
"description": "Type of charges that apply for international transfers. Accepted values are: \"SHARED\", \"RECEIVER\", \"SENDER\". \n >(i)SHARED: Shared charges. The sender pays his bank's outgoing transfer charge. The beneficiary receives the transfer amount minus the correspondent interchange charges.\n>(ii)RECEIVER: Chareges are paid by the receiver. The sender doesn't pay any charge. The beneficiary receives the transfer amount minus all transfer charges.\n>(iii)SENDER: Charges are paid by the sender. The beneficiary receives all the transfer's amount. Charges of the sender's bank and the recipient's bank are borne by the sender. Optional parameter in case of being a SEPA transfer (it will always be SHARED). ",
"example": "SHARED"
},
"currency": {
"type": "string",
"description": "Currency",
"example": "EUR"
},
"amount": {
"type": "string",
"description": "Amount",
"example": "100.00"
}
},
"additionalProperties": false,
"required": [
"currency",
"amount",
"spending_policy"
]
}
Transfer amount and currency value of the transfer.
{
"properties": {
"currency": {
"type": "string",
"example": "EUR",
"description": "Currency"
},
"amount": {
"type": "string",
"example": "100.00",
"description": "Amount"
}
},
"additionalProperties": false,
"required": [
"amount",
"currency"
]
}
List of custom errors
{
"type": "array",
"items": {
"$ref": "#\/definitions\/custom-error"
}
}
This object will contain the signature_token obtained previously (using the Payment Initiation API). This signature token is needed to execute the payment.
{
"properties": {
"signature_token": {
"type": "string",
"example": "eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJHT0lUIiwib3BlcmF0aW9uIjp7Im9wZXJhdGlvbkRhdGEiOnsiam91cm5leSI6IlBJU1AtUEFZTUVOVFMiLCJvcmlnaW5BY2NvdW50IjoiRVMwMCIsImJlbmVmaWNpYXJ5SW5mbyI6eyJiZW5lZmljaWFyeU5hbWUiOiJEYW5pZWwiLCJkZXN0aW5hdGlvbkFjY291bnQiOiJFUzAxIn0sInBheW1lbnRUeXBlIjoic2VwYV9jcmVkaXRfdHJhbnNmZXIiLCJwb2xpY3kiOiJTSEFSRUQiLCJhbW91bnQiOjYwLjAsImN1cnJlbmN5IjoiRVVSIn0sInJlcXVlc3RJRCI6IjMxMzIzNTIyMjIyMzI2MjEjIzMyMzIxMjMyMyIsImFwcERldGFpbHMiOnsiY2xpZW50SWQiOiI0ODQxNWIzNC02NTBjLTRmM2EtYmIxOS0zMzU2ZWE0MDZiOTkiLCJjbGllbnROYW1lIjoiSWRlYWxpc3RhIFMuQSIsIm9yZ0lkIjoiNTljOGU5YmZlNGIwYmFhMjBjMzBhMDcyIiwib3JnTmFtZSI6IklkZWFsaXN0YSBDb211bmljYWNpb25lcyJ9fX0.AES0acLmk2p14dGBdVvMNcq1asKXDpYv37hh7clm5Dl1Gtu4SvrVOxJvS8Cv_3COp72teh7giTNdXdOAmI9vkA"
}
},
"additionalProperties": false,
"required": [
"signature_token"
]
}
This object contains all the information related to the operation that has been executed by the API.
{
"properties": {
"payment_data": {
"$ref": "#\/definitions\/paymentData",
"description": "Contains information about the payment that has been executed.",
"example": "{ \"payment_id\": \"192903890\",\t \"fee\": { \"spending_policy\": \"shared\", \"currency\": \"EUR\", \"amount\": \"60.20\" }"
},
"status": {
"type": "string",
"description": "Success: successful payment \/ failure: the payment could not be executed.",
"example": "Success"
},
"Request-ID": {
"type": "string",
"description": "Autogenerated identifier related to the request. The original Request-ID that was generated during initiation will be returned.",
"example": "12345##8edf7f090a2d118c"
}
},
"additionalProperties": false,
"required": [
"payment_data"
]
}
{
"properties": {
"interaction_id": {
"type": "string"
},
"signature_token": {
"type": "string"
},
"app": {
"$ref": "#\/definitions\/appInfo"
},
"operation": {
"type": "string"
},
"idempotent_key": {
"type": "string"
},
"shortToken": {
"type": "boolean"
}
},
"additionalProperties": false,
"required": [
"signature_token",
"app",
"shortToken",
"operation"
]
}
This object contains the information of the payment provided in the body of the API response.
{
"properties": {
"payment_id": {
"type": "string",
"description": "Payment ID generated by the payment system, if the operation was successful.",
"example": "123224"
},
"fee": {
"$ref": "#\/definitions\/fee",
"description": "Information related to the fee associated to the transfer.",
"example": " { \"spending_policy\": \"shared\", \"currency\": \"EUR\", \"amount\": \"60.20\" }"
},
"value": {
"$ref": "#\/definitions\/value",
"description": "Currency and amount for the transfer.",
"example": "{ \"currency\": \"EUR\", \"amount\": \"60.20\" }"
},
"type": {
"type": "string",
"description": "Transfer type: sepa_credit_transfer, international_transfer",
"example": "sepa_credit_transfer"
}
},
"additionalProperties": false,
"required": [
"type",
"value",
"fee",
"payment_id"
]
}
{
"properties": {
"clientId": {
"type": "string"
},
"clientName": {
"type": "string"
},
"orgId": {
"type": "string"
},
"orgName": {
"type": "string"
}
},
"additionalProperties": false,
"required": [
"clientId",
"clientName"
]
}
{
"properties": {
"payment_data": {
"$ref": "#\/definitions\/paymentData",
"description": "Contains information about the payment that has been executed.",
"example": "{ \"payment_id\": \"192903890\",\t \"fee\": { \"spending_policy\": \"shared\", \"currency\": \"EUR\", \"amount\": \"60.20\" }"
},
"status": {
"type": "string",
"description": "Success: successful payment \/ failure: the payment could not be executed.",
"example": "Success"
},
"Request-ID": {
"type": "string",
"description": "Autogenerated identifier related to the request. The original Request-ID that was generated during initiation will be returned.",
"example": "12345##8edf7f090a2d118c"
}
},
"additionalProperties": false,
"required": [
"payment_data"
]
}
