Payment Initiation 6.3.2
Description
The Payment Initiation Product provides seamless and efficient payment functionalities to enhance your payment services
Main features:
- Through the API it is possible to send domestic, cross border and SEPA credit transfer payments and to make instant money transfers between SEB accounts.
- Register standing payment orders and cancel initiated payments before they are booked and the cut-off time has passed.
- Request the Payment Initiation Templates to get a list of supported products and to populate your API calls with ease.
- Confirm if a certain balance is available on an account through Fund Confirmation.
Authorization
SEB uses 3-legged authorization to delegate access to user data according to the OAuth 2.0 protocol. The OAuth flow is a way for your application to get an access token and a refresh token.
Authorization is initiated using the separate Authorization API.
We use scopes to authorize access to APIs. Scope is required as a parameter in the API call to the authorize endpoint.
https://api-sandbox.sebgroup.com/mga/sps/oauth/oauth20/authorize
The following scopes are required:
psd2_accounts
psd2_payments
You will need to submit both scopes to get a valid token. For further information see instructions for how get a token here.
Note!
You must create one application for private user data and one application for corporate user data when calling the Account Information and Payment Initiation API. This will be required when granted access to production data.
Sandbox
This API is included in the dynamic sandbox environment so you can test your application before accessing production data.
The test users in the dynamic sandbox consist of five private individuals, where two have access to corporate accounts from the same company.
Use the Personal Identification Numbers below in the Authorization flow to access the various test user’s data. Include the PSU-Corporate-ID parameter in the API call to trigger corporate data in the dynamic sandbox. Leaving this field black will trigger private sandbox data.
Sandbox users for initiating payments:
| Sandbox Identification Number | PSU-Corporate-ID | Sandbox data access Private access |
Corporate access |
| 9311219639 | 40073144970009 | Payments from all accounts | Access to one account |
| 9311219589 | 40073144970009 | Payments from all accounts | Access to two accounts |
| 8811215477 | ... | Payments from all accounts | ... |
| 8811212862 | ... | Payments from all accounts | ... |
| 8311211356 | ... | Payments from all accounts | ... |
State
Api for handling linked authentications
Paths
/payments/{paymentProduct}
Creates a payment initiation
Creates a payment initiation from the provided information. Corporate payment initiations can only be performed if the "PSU-Corporate-Id" header is set. In production the call also needs to come from a corporate TPP client-id.
The payment API accepts different kinds of payment instructions. Templates are used to help the consumer to select the right payment product and they can be retrieved from the templates API. Access the template list endpoint to find all the supported payment products, 'GET /templates'. Note that the debtor account (sender) for private payments is always an IBAN and the creditor account type is dependent on the selected template (payment product). The available debtor accounts can either be obtained from the customer or by using the accounts API.
The "Location" header of the response will contain the URL pointing to the newly created resource. 'Location → /payments/swedish-domestic-private-credit-transfers/STOHYD01180208082256128737000001' The response will also include the paymentId as a field in the body.
During the payment initiation the payment systems will process the payment data asynchronously. The client must continuously check the status of the payment to make sure that the payment is ready for the next step in the payment process.
Transfers between customers own accounts will be processed directly and queued for execution on the requested execution-date. Other payments must be signed by the customer (e.g. through Mobilt BankID) before the payment is executed. Signing can be initiated once the associated authentication link is visible in the status endpoint. The payments can either be signed one by one by creating an authorisations sub-resource under the payment; or multiple payments can be signed at once by creating a signing basket (with a group of payment ids) and then creating an authorisations sub-resource under the signing basket.
Sandbox environment; the mock will reset all data each sunday at midnight, a customer can also reset their own data by calling the reset endpoint.
Describes which payment product this call is in reference to. Needs to match whichever payment you are requesting information for. Example value "swedish-domestic-private-bankgiros"
Payment instruction containing information about the payment.
{
"schema": {
"description": "Instruction for a payment type, fields are relevant only for specific payment types this should be checked in the template service.",
"type": "object",
"properties": {
"templateId": {
"type": "string",
"description": "Optional field in input. If provided it needs to match product in path.",
"example": "swedish-domestic-private-bankgiros"
},
"endToEndIdentification": {
"type": "string"
},
"remittanceInformationStructured": {
"description": "Used for OCR with bankgiro and postgiro or SCOR with SEPA payments. If you provide this then omit remittanceInformationUnstructured.",
"type": "object",
"properties": {
"reference": {
"type": "string",
"description": "The structured remittance reference number for the payment.",
"example": "234634699"
},
"referenceType": {
"type": "string",
"description": "Type of reference number.",
"enum": [
"OCR",
"SCOR"
]
}
}
},
"remittanceInformationUnstructured": {
"description": "Message field to creditor.",
"type": "string",
"maxLength": 100,
"example": "Liten drake"
},
"debtorAccountMessage": {
"description": "A message shown on debtor account statement, max length depending on payment product",
"type": "string",
"example": "Text for my payment"
},
"creditorAccountMessage": {
"description": "A message shown on creditor account statement. Only usable with some payment products.",
"type": "string",
"example": "Text to you"
},
"requestedExecutionDate": {
"type": "string",
"description": "Requested execution date of transaction in format yyyy-mm-dd. If the date is not a valid bank date for the payment product, then the payment will be rejected.",
"example": "2018-02-12"
},
"instructedAmount": {
"properties": {
"currency": {
"type": "string",
"example": "SEK"
},
"amount": {
"type": "string",
"example": "345.50"
},
"equivalentAmount": {
"description": "Amount in SEK for non SEK account",
"type": "string",
"example": ""
}
},
"type": "object"
},
"debtorAccount": {
"properties": {
"iban": {
"description": "Debtor account number in IBAN format",
"type": "string",
"example": "SE8050000000052800025220"
},
"bban": {
"description": "Debtor account number in BBAN format, only for corporate payments.",
"type": "string",
"example": "52800025220"
}
},
"type": "object"
},
"creditorAccount": {
"description": "Conditional, only one of the properties may be used.",
"properties": {
"iban": {
"type": "string",
"example": "SE8050000000052800025220"
},
"bban": {
"type": "string",
"example": "52800025220"
},
"pgnr": {
"type": "string",
"example": "44580264"
},
"bgnr": {
"type": "string",
"example": "0001212121"
}
},
"type": "object"
},
"creditorAddress": {
"description": "Address fields can be added for some payment types. See each individual template.",
"properties": {
"street": {
"type": "string",
"example": "The Svedberg street 9999"
},
"country": {
"type": "string"
},
"city": {
"type": "string",
"example": "Stockholm"
},
"postalCode": {
"type": "string",
"example": "BE19271"
}
}
},
"creditorDetails": {
"description": "See specific payment types."
},
"bankCharges": {
"description": "See specific payment types.",
"type": "string"
},
"debtorReceipt": {
"type": "boolean",
"description": "Receipt can be requested for some payment types."
},
"instructionId": {
"description": "All fields after this are only relevant to corporate payments. The remitters own reference which will be stated in the transaction reporting by the bank in order to identify the transaction. It will not be forwarded to the beneficiary.",
"type": "string",
"example": "Payment info"
},
"chargeBearer": {
"description": "Charge sharing instructions for corporate payments.",
"type": "string",
"example": "DEBT"
},
"debtorAgentBic": {
"type": "string",
"example": "DEUTDEFFXXX"
},
"categoryPurpose": {
"type": "string",
"description": "Value to be used to determine if the payment is a Split payment (VATX) or a Tax payment (TAXS)"
},
"intermediaryAgentBic": {
"type": "string",
"example": "DEUTDEFFXXX"
},
"creditorAgentBic": {
"type": "string",
"example": "ESSESSESSXXX"
},
"creditorAgentOther": {
"type": "object",
"properties": {
"clearingSystemId": {
"type": "string",
"example": "“GBDSC”"
},
"memberId": {
"type": "string",
"example": "“404865”"
}
}
},
"regulatoryReporting": {
"type": "array",
"items": {
"type": "object",
"properties": {
"debitCreditReportingIndicator": {
"type": "string",
"example": "DEBT"
},
"reportingCode": {
"type": "string"
},
"reportingInformation": {
"type": "string"
}
}
}
}
}
}
}Accepted content types.
{
"enum": [
"application\/json"
]
}Parameter is either an optional request identification id or a payment reference identification used when initiatating a payment. Parameter is set by the third party. Duplicate value on payment reference identification is not allowed. If stated in the request it will be returned in the response. ID of the request, unique to the call, as determined by the initiating party. Same value will be returned in each successful call. Duplicate values being used will lead to errors in payment creation. Example value "ccae853f-4f23-47a3-bd9b-6f6e75a1d3d2"
Contains the Bearer Token for OAuth 2.0. Example value "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1d_etc"
The IP Address of the PSU, as determined in the communication between PSU and TPP, must be provided when POST'ing a payment or authorisation. During other calls supply the value if applicable. Provided in either IPv4 or IPv6 format. Example value "129.178.88.88"
Send in an expected user-id to verify that the used Authorization token matches the user expected. Can be set to 10 or 12 digit personal number, or a 6 digit XID
Checks if the correct type of user is checked in. PERSNR checks that PSU is logged in using a personal number (can still be either private or corporate user), whereas XID checks that a SEB corporate user is logged in using an SEB specific ID
Include in any request aimed at accessing corporate accounts or corporate payment types. This is the 14 digit SEB identifier for the company. When this header is included all tasks will be performed for this corporation based on the PSU having access rights. Note that this header shall not be present when accessing payment endpoints for private accounts.
Provide this value to improve Risk Scoring. The forwarded header field of the HTTP request between PSU and TPP, if available. Example value "8080"
Provide this value to improve Risk Scoring. The forwarded header field of the HTTP request between PSU and TPP, if available. Example value "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/66.0.3359.181 Safari/537.36"
Provide this value to improve Risk Scoring. The forwarded Geo Location of the corresponding HTTP request between PSU and TPP if available. See RFC2426. Example value "GEO:52.506931,13.144558"
Provide this value to improve Risk Scoring. The forwarded header field of the HTTP request between PSU and TPP, if available. Example value "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,/;q=0.8"
Provide this value to improve Risk Scoring. The forwarded header field of the HTTP request between PSU and TPP, if available. Example value "ISO-8859-1"
Provide this value to improve Risk Scoring. The forwarded header field of the HTTP request between PSU and TPP, if available. Example value "gzip, deflate"
Provide this value to improve Risk Scoring. The forwarded header field of the HTTP request between PSU and TPP, if available. Example value "en-US,en;q=0.9,sv;q=0.8"
Provide this value to improve Risk Scoring. HTTP method used at the PSU – TPP interface, if available. Example value "POST"
Provide this value to improve Risk Scoring. UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. Example value "05a18f38-c218-4d1c-a9d0-ac36763580e1"
Payment initiation created.
Same value that was provided in the request.
The absolute URL where the resource can be found.
Error caused by bad input data. Example causes
- Setting value of a parameter in provided "Template" with incorrect format.
- Not including required input parameters, such as 'Accept' header.
Internal server error.
- Error caused by remote technical issues, this status code is used for unforeseen technical issues
- Please contact support and include information from the instance field.
Service unavailable.
- Returned when service is unavailable due to scheduled reasons, such as maintenance.
/payments/{paymentProduct}/{paymentId}
Get the payment initiation.
Returns the previously posted payment initiation. Any additional fields that are not part of the chosen payment product will be stripped away.
Describes which payment product this call is in reference to. Needs to match whichever payment you are requesting information for. Example value "swedish-domestic-private-bankgiros"
id of the payment initation
Accepted content types.
{
"enum": [
"application\/json"
]
}Parameter is either an optional request identification id or a payment reference identification used when initiatating a payment. Parameter is set by the third party. Duplicate value on payment reference identification is not allowed. If stated in the request it will be returned in the response. ID of the request, unique to the call, as determined by the initiating party. Same value will be returned in each successful call. Duplicate values being used will lead to errors in payment creation. Example value "ccae853f-4f23-47a3-bd9b-6f6e75a1d3d2"
Contains the Bearer Token for OAuth 2.0. Example value "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1d_etc"
A payment initiaton
Same value that was provided in the request.
Error caused by bad input data.
Example causes include
Not including required input parameters, such as 'Accept' header.
Requesting information for a customer without appropriate access.
Not found.
Requesting a non-existent payment or payment product.
Requesting incorrectly constructed URLs will return this error
Method Not Allowed.
- This method is currently not available for corporate access, only for payments to private individuals
Internal server error.
Error caused by remote technical issues, this status code is used for unforeseen technical issues.
Please contact support and include information from the instance field.
Service unavailable.
- Returned when service is unavailable due to scheduled reasons, such as maintenance.
Delete the payment initiation.
Cancels the addressed payment if received before cut-off time for payment product. SCA by customer is not required.
The successful response to a deletion of a payment falls into three categories depending on: payment product type; signed by customer or not; and the status in the payment process system.
- Payment is deleted immediately. This response for this is the http code 204 No Content.
- Payment is deleted asynchronosly. The response for this is the http code 202 Accepted. The client must then check the status of the payment. If the payment status switches to CANC (within a few minutes), then the payment has been deleted.
- Payment cannot be deleted. The response for this is the http code 202 Accepted. The client must then check the status of the payment. If the payment status does not switch to CANC (within a few minutes), then the payment cannot be cancelled. Additional delete requests will not cancel the payment.
- On some errors - such as trying to delete an already rejected payment a 400 Input Error status can be received. See responses.
Describes which payment product this call is in reference to. Needs to match whichever payment you are requesting information for. Example value "swedish-domestic-private-bankgiros"
id of the payment initation
Accepted content types.
{
"enum": [
"application\/json"
]
}Parameter is either an optional request identification id or a payment reference identification used when initiatating a payment. Parameter is set by the third party. Duplicate value on payment reference identification is not allowed. If stated in the request it will be returned in the response. ID of the request, unique to the call, as determined by the initiating party. Same value will be returned in each successful call. Duplicate values being used will lead to errors in payment creation. Example value "ccae853f-4f23-47a3-bd9b-6f6e75a1d3d2"
Contains the Bearer Token for OAuth 2.0. Example value "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1d_etc"
Deletion request was accepted. Please check the status of the payment. Transaction status CANC indicates that the payment is successfully deleted.
Same value that was provided in the request.
Immediate payment deletion was successful
Same value that was provided in the request.
Error caused by bad input data. Example causes include
- Attempting to delete a rejected payment
- Not including required input parameters, such as 'Accept' header.
- Requesting information for a customer without appropriate access.
Not found.
- Requesting a non-existent payment or payment product.
- Requesting incorrectly constructed URLs will return this error
Internal server error.
- Error caused by remote technical issues, this status code is used for unforeseen technical issues.
- Please contact support and include information from the instance field.
Service unavailable.
- Returned when service is unavailable due to scheduled reasons, such as maintenance.
/payments/{paymentProduct}/{paymentId}/status
Payment initiation status
During the payment initiation the payment systems will process payment data asynchronously. The consumer of the API must continuously check the status of the payment to make sure that the payment is ready for the next step in the payment process. The status request uses the payment id value that was returned in the Location header when posting the payment data.
The transaction status can have the following states
- RCVD, Received, The payment has been received by SEB. To determine if payment is ready for signing, check the links block. Recommended polling interval is 5 seconds;
- RCVD + link, Received, If "startAuthorisationWithMethodSelection" link is shown, the payment system has validated the payment. Please post authenticationMethodId to suitable authorisations endpoint to continue payment flow.
- ACTC, AcceptedTechnicalValidation, AcceptedCustomerProfile, The payment initiation is signed and stored for execution and should be executed on the desired execution date.
- ACSC, AcceptedSettlementCompleted, The payment has been executed on the desired date.
- CANC, Cancelled, The payment has been cancelled and will not be executed
- RJCT, Rejected, The payment initiation failed. Additional information may be supplied to explain why the payment could not be made. A failed payment cannot be corrected, it has to be posted again as a new payment.
Payments must be signed by the customer (i.e. through Mobilt BankID) before the payment is executed. This step can be initiated once the associated authentication link is visible in the status endpoint. The payments can either be signed one by one by creating an authorisations sub-resource under the payment; or multiple payments can be signed at once by creating a signing basket (with a group of payment ids) and then creating an authorisations sub-resource under the signing basket.
Describes which payment product this call is in reference to. Needs to match whichever payment you are requesting information for. Example value "swedish-domestic-private-bankgiros"
id of the payment initation
Accepted content types.
{
"enum": [
"application\/json"
]
}Parameter is either an optional request identification id or a payment reference identification used when initiatating a payment. Parameter is set by the third party. Duplicate value on payment reference identification is not allowed. If stated in the request it will be returned in the response. ID of the request, unique to the call, as determined by the initiating party. Same value will be returned in each successful call. Duplicate values being used will lead to errors in payment creation. Example value "ccae853f-4f23-47a3-bd9b-6f6e75a1d3d2"
Contains the Bearer Token for OAuth 2.0. Example value "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1d_etc"
A payments status
Same value that was provided in the request.
Error caused by bad input data.
Example causes include
- Not including required input parameters, such as 'Accept' header.
- Requesting information for a customer without appropriate access.
Not found.
- Requesting a non-existent payment or payment product.
- Requesting incorrectly constructed URLs will return this error
Internal server error.
- Error caused by remote technical issues, this status code is used for unforeseen technical issues
- Please contact support and include information from the instance field.
Service unavailable.
- Returned when service is unavailable due to scheduled reasons, such as maintenance.
/payments/{paymentProduct}/{paymentId}/authorisations
Starts a single payment authentication procedure for the end customer.
The payment authorization sub resource is used to sign a single payment with one signature.
When the status of the payment is "RCVD" and the status response contains a link to "startAuthorisationWithMethodSelection" the payment is ready for signing. The response from the "/status" call will also contain a list of "scaMethods" and the appropriate "authenticationMethodId" must be choosen and provided in the request body. There are three authentication methods for payment authorization - “mobiltbankid”, “digipass” and “bankIdOnCardDecoupled”. Authentication methods depends on customer type (Private/Corporate).
This will create an authorization resource, which can be checked if you want to follow the detailed progress of the customer signing. To check if payment has been signed and stored, call payment status endpoint.
The response from this method will contain a psuMessage field, which should be shown to the end customer so that they can initiate the correct signing action. The field tppMessages will contain messages directed at the client informing them about actions to facilitate signing. For BankID authentication methods there is no further actions for client. In case of signing with Digipass, "scaRedirect" link is provided in response. Client must redirect customer to that link, or link must be followed by customer to finish signing.
In sandbox environment all signings are mocked and processed within 30 seconds automatically. For digipass signing in sandbox "scaRedirect" link is not real.
Describes which payment product this call is in reference to. Needs to match whichever payment you are requesting information for. Example value "swedish-domestic-private-bankgiros"
id of the payment initation
Accepted content types.
{
"enum": [
"application\/json"
]
}Json object containing value for selected authentication method.
{
"schema": {
"type": "object",
"properties": {
"authenticationMethodId": {
"type": "string",
"description": "Field with the correct SCA method to use for payment. Equivalent to authenticationMethodId field of SCAMethod shown.",
"example": "mobiltbankid"
}
}
}
}Parameter is either an optional request identification id or a payment reference identification used when initiatating a payment. Parameter is set by the third party. Duplicate value on payment reference identification is not allowed. If stated in the request it will be returned in the response. ID of the request, unique to the call, as determined by the initiating party. Same value will be returned in each successful call. Duplicate values being used will lead to errors in payment creation. Example value "ccae853f-4f23-47a3-bd9b-6f6e75a1d3d2"
Contains the Bearer Token for OAuth 2.0. Example value "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1d_etc"
The IP Address of the PSU, as determined in the communication between PSU and TPP, must be provided when POST'ing a payment or authorisation. During other calls supply the value if applicable. Provided in either IPv4 or IPv6 format. Example value "129.178.88.88"
Mandatory header if chosen authenticationMethodId is “digipass”. Customer must be redirected to this url after payment authorization is completed. Example value "https://www.seb.se"
Authorization is started using the provided authorization method.
Same value that was provided in the request.
Error caused by bad input data. Example causes include
- Not including required input parameters, such as 'Accept' header.
- Specifying an unsupported SCA method in request body.
Not found.
- Initiating signing for a non-existent payment or payment product.
- Requesting incorrectly constructed URLs will return this error
Internal server error.
- Error caused by remote technical issues, this status code is used for unforeseen technical issues
- Please contact support and include information from the instance field.
Service unavailable.
- Returned when service is unavailable due to scheduled reasons, such as maintenance.
Get a list of authorisations associated with this payment
Gets a list of authorisation ids, including any active or previously failed authorisations for a specific payment.
Describes which payment product this call is in reference to. Needs to match whichever payment you are requesting information for. Example value "swedish-domestic-private-bankgiros"
id of the payment initation
Accepted content types.
{
"enum": [
"application\/json"
]
}Parameter is either an optional request identification id or a payment reference identification used when initiatating a payment. Parameter is set by the third party. Duplicate value on payment reference identification is not allowed. If stated in the request it will be returned in the response. ID of the request, unique to the call, as determined by the initiating party. Same value will be returned in each successful call. Duplicate values being used will lead to errors in payment creation. Example value "ccae853f-4f23-47a3-bd9b-6f6e75a1d3d2"
Contains the Bearer Token for OAuth 2.0. Example value "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1d_etc"
A list of the authorisations associated with this payment initiation.
Same value that was provided in the request.
Error caused by bad input data.
Example causes include
- Not including required input parameters, such as 'Accept' header.
- Requesting information for a customer without appropriate access.
Not found.
- Requesting a non-existent payment or payment product.
- Requesting incorrectly constructed URLs will return this error
Internal server error.
- Error caused by remote technical issues, this status code is used for unforeseen technical issues.
- Please contact support and include information from the instance field.
Service unavailable.
- Returned when service is unavailable due to scheduled reasons, such as maintenance.
/payments/{paymentProduct}/{paymentId}/authorisations/{authorisationId}
Get authorization resource
When a customer signing is initiated, a corresponding Authorization resource will be created. To see the progress of the ongoing signing this resource should be retrieved.
The scaStatus field can have the following values
- started -> Signing is initialized and the PSU should sign.
- finalized -> Signing has finished succesfully.
- failed -> Signing has ended unsucessfully, i.e due to timeout or cancellation.
Describes which payment product this call is in reference to. Needs to match whichever payment you are requesting information for. Example value "swedish-domestic-private-bankgiros"
id of the payment initation
id of the authorization resource
Accepted content types.
{
"enum": [
"application\/json"
]
}Parameter is either an optional request identification id or a payment reference identification used when initiatating a payment. Parameter is set by the third party. Duplicate value on payment reference identification is not allowed. If stated in the request it will be returned in the response. ID of the request, unique to the call, as determined by the initiating party. Same value will be returned in each successful call. Duplicate values being used will lead to errors in payment creation. Example value "ccae853f-4f23-47a3-bd9b-6f6e75a1d3d2"
Contains the Bearer Token for OAuth 2.0. Example value "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1d_etc"
An authorization object
Same value that was provided in the request.
Error caused by bad input data.
Example causes include
- Not including required input parameters, such as 'Accept' header.
- Requesting information for a customer without appropriate access.
Not found.
- Requesting a non-existent payment, authorisation or payment product.
- Requesting incorrectly constructed URLs will return this error
Internal server error.
- Error caused by remote technical issues, this status code is used for unforeseen technical issues
- Please contact support and include information from the instance field.
Service unavailable.
- Returned when service is unavailable due to scheduled reasons, such as maintenance.
/signing-baskets
Starts a multiple payment authentication procedure for the end customer. Creates a signing basket containing payment ids in the request body.
The signing basket is used to sign multiple payments with one signature. First create a signing basket containing the payment ids that should be signed. The response will contain a list of available SCA methods that can be used to sign the payments. Then create an authorisation sub resource using the selected payment SCA method.
Accepted content types.
{
"enum": [
"application\/json"
]
}Object containing array of paymentIds
{
"schema": {
"type": "object",
"properties": {
"paymentIds": {
"type": "array",
"description": "Array of paymentIds to include in the basket. If any of the payments are not signable the creation will be rejected.",
"example": [
"STOHYD75412344553",
"STOHYD1515151515151"
],
"items": {
"type": "string"
}
}
}
}
}Parameter is either an optional request identification id or a payment reference identification used when initiatating a payment. Parameter is set by the third party. Duplicate value on payment reference identification is not allowed. If stated in the request it will be returned in the response. ID of the request, unique to the call, as determined by the initiating party. Same value will be returned in each successful call. Duplicate values being used will lead to errors in payment creation. Example value "ccae853f-4f23-47a3-bd9b-6f6e75a1d3d2"
Contains the Bearer Token for OAuth 2.0. Example value "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1d_etc"
A signing basket is created for provided payment-ids.
Same value that was provided in the request.
Error caused by bad input data. Example causes include
- Not including required input parameters, such as 'Accept' header.
- Specifying a payment that can not be signed, or does not exist in request body.
Not found.
- Initiating signing for non-existent payment ID or payment product.
- Requesting incorrectly constructed URLs will return this error
Internal server error.
- Error caused by remote technical issues, this status code is used for unforeseen technical issues
- Please contact support and include information from the instance field.
Service unavailable.
- Returned when service is unavailable due to scheduled reasons, such as maintenance.
/signing-baskets/{basketId}
Returns information on a signing basket.
Returns the which payments are part of the signing basket and the overall transaction status.
The transaction status can be
- RJCT - This basket can no longer be used to sign for the payments (e.g. it contains a payment that has been rejected). Please create a new basket with the relevant payments.
- RCVD - The basket is ready for signing.
- ACTC - All payments in the basket are signed and will be executed.
id of the basket resource
Accepted content types.
{
"enum": [
"application\/json"
]
}Parameter is either an optional request identification id or a payment reference identification used when initiatating a payment. Parameter is set by the third party. Duplicate value on payment reference identification is not allowed. If stated in the request it will be returned in the response. ID of the request, unique to the call, as determined by the initiating party. Same value will be returned in each successful call. Duplicate values being used will lead to errors in payment creation. Example value "ccae853f-4f23-47a3-bd9b-6f6e75a1d3d2"
Contains the Bearer Token for OAuth 2.0. Example value "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1d_etc"
Information on a basket-id
Same value that was provided in the request.
Error caused by bad input data. Example causes include
- Not including required input parameters, such as 'Accept' header.
Not found.
Requesting a non-existent signing basket.
Requesting incorrectly constructed URLs will return this error
Method Not Allowed.
- This method is currently not available for corporate access, only for signing of payments to private individuals
Internal server error.
Error caused by remote technical issues, this status code is used for unforeseen technical issues
Please contact support and include information from the instance field.
Service unavailable.
- Returned when service is unavailable due to scheduled reasons, such as maintenance.
/signing-baskets/{basketId}/authorisations
Selects a SCA (Strong Customer Authentication) method and creates an authorization for payments in the basket. The end customer should sign the payment using this method.
Selects and starts the authentication procedure for the end customer. The selected SCA method id is sent in the request. There are three authentication methods for payment authorization - “mobiltbankid”, “digipass” and “bankIdOnCardDecoupled”. Authentication methods depends on customer type (Private/Corporate). If the basket contains any rejected payments or only unsignable payments the request will be rejected.
Payment ids that are about to signed will be returned in the response and this list may differ from all the payments in the payment basket. Payments that are already in the middle of the signing process and already signed payments will be excluded from the created authorization resource. As such the created authorization might not contain all payments in the basket, so please check the "paymentIds" field. In case of signing with Digipass, "scaRedirect" link is provided in response. Client must redirect customer to that link, or link must followed by customer to finish signing.
In sandbox environment all signings are mocked and processed within 30 seconds automatically. For digipass signing in sandbox "scaRedirect" link is not real.
id of the basket resource
Accepted content types.
{
"enum": [
"application\/json"
]
}Json object containing value for selected authentication method.
{
"schema": {
"type": "object",
"properties": {
"authenticationMethodId": {
"type": "string",
"description": "Field with the correct SCA method to use for payment. Equivalent to authenticationMethodId field of SCAMethod shown.",
"example": "mobiltbankid"
}
}
}
}Parameter is either an optional request identification id or a payment reference identification used when initiatating a payment. Parameter is set by the third party. Duplicate value on payment reference identification is not allowed. If stated in the request it will be returned in the response. ID of the request, unique to the call, as determined by the initiating party. Same value will be returned in each successful call. Duplicate values being used will lead to errors in payment creation. Example value "ccae853f-4f23-47a3-bd9b-6f6e75a1d3d2"
Contains the Bearer Token for OAuth 2.0. Example value "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1d_etc"
The IP Address of the PSU, as determined in the communication between PSU and TPP, must be provided when POST'ing a payment or authorisation. During other calls supply the value if applicable. Provided in either IPv4 or IPv6 format. Example value "129.178.88.88"
Mandatory header if chosen authenticationMethodId is “digipass”. Customer must be redirected to this url after payment authorization is completed. Example value "https://www.seb.se"
Authorization is started using the provided authorization method.
Same value that was provided in the request.
Error caused by bad input data. Example causes include
- Not including required input parameters, such as 'Accept' header.
- Specifying an unsupported SCA method in request body.
- Requesting information for a customer without appropriate access.
Not found.
- Initiating signing for non-existent signing basket.
- Requesting incorrectly constructed URLs will return this error
Internal server error.
- Error caused by remote technical issues, this status code is used for unforeseen technical issues
- Please contact support and include information from the instance field.
Service unavailable.
- Returned when service is unavailable due to scheduled reasons, such as maintenance.
/signing-baskets/{basketId}/authorisations/{authorisationId}
Get authorization resource
Retrieve this resource for information on a specific signing or to see the progress of an authorization signing.
Payment ids that are about to signed will be returned in the response. Payments that are already in the middle of the signing process and already signed payments will be excluded from the created authorization resource. As such the created authorization might not contain all payments in the basket, so please check the "paymentIds" field.
The scaStatus field can have the following values
- started -> Signing is initialized and the PSU should sign.
- finalized -> Signing has finished succesfully.
- failed -> Signing has ended unsucessfully, i.e due to timeout or cancellation.
id of the basket resource
id of the authorization resource
Accepted content types.
{
"enum": [
"application\/json"
]
}Parameter is either an optional request identification id or a payment reference identification used when initiatating a payment. Parameter is set by the third party. Duplicate value on payment reference identification is not allowed. If stated in the request it will be returned in the response. ID of the request, unique to the call, as determined by the initiating party. Same value will be returned in each successful call. Duplicate values being used will lead to errors in payment creation. Example value "ccae853f-4f23-47a3-bd9b-6f6e75a1d3d2"
Contains the Bearer Token for OAuth 2.0. Example value "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1d_etc"
A payments status
Same value that was provided in the request.
Error caused by bad input data.
Example causes include
- Not including required input parameters, such as 'Accept' header.
- Requesting information for a customer without appropriate access.
Not found.
- Requesting a non-existent signing basket or authorisation.
- Requesting incorrectly constructed URLs will return this error
Internal server error.
- Error caused by remote technical issues, this status code is used for unforeseen technical issues
- Please contact support and include information from the instance field.
Service unavailable.
- Returned when service is unavailable due to scheduled reasons, such as maintenance.
/payments/mock/resetall
Sandbox only; Reset all mock transactions and authorisations for all users.
This endpoint exists ONLY in the Sandbox environment, there is no production equivalent. Deletes any created transactions in the mock, making funds available for further testing. A call to this endpoint removes all such entitys associated with provided authorisation, for all mock-users.
Parameter is either an optional request identification id or a payment reference identification used when initiatating a payment. Parameter is set by the third party. Duplicate value on payment reference identification is not allowed. If stated in the request it will be returned in the response. ID of the request, unique to the call, as determined by the initiating party. Same value will be returned in each successful call. Duplicate values being used will lead to errors in payment creation. Example value "ccae853f-4f23-47a3-bd9b-6f6e75a1d3d2"
Contains the Bearer Token for OAuth 2.0. Example value "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1d_etc"
A message for succesfull reset.
Same value that was provided in the request.
Definitions
Response to a reset request for the mock.
{
"type": "object",
"properties": {
"resultMessage": {
"type": "string",
"description": "Human readable result of reset."
}
}
}
Array of all authorisationId GUIDs associated with a payment.
{
"type": "object",
"properties": {
"authorisationIds": {
"type": "array",
"items": {
"type": "string",
"description": "GUID, reference to specific authorization resource",
"example": "ad155467-1505-41c9-9158-bc1811fc632b"
}
}
}
}
{
"type": "object",
"properties": {
"paymentIds": {
"type": "array",
"description": "Array of paymentIds to include in the basket. If any of the payments are not signable the creation will be rejected.",
"example": [
"STOHYD75412344553",
"STOHYD1515151515151"
],
"items": {
"type": "string"
}
}
}
}
{
"type": "object",
"properties": {
"paymentIds": {
"type": "array",
"description": "Array of paymentIds in the created basket.",
"example": [
"STOHYD75412344553",
"STOHYD1515151515151"
],
"items": {
"type": "string",
"description": "Array of paymentIds"
}
},
"basketId": {
"type": "string",
"description": "GUID, resource ID of the basket.",
"example": "c57297dc-fa74-4cad-a328-40258ae7976f"
},
"transactionStatus": {
"type": "string",
"description": "Lowest status of any payment in the basket. Baskets with a status oc RJCT or ACTC can not be used to initialize an authorization.",
"example": "RCVD",
"enum": [
"RJCT",
"RCVD",
"ACTC"
]
},
"scaMethods": {
"description": "Array of available signing methods. Please use the authenticationMethodIdId as input to the signing.",
"type": "array",
"items": {
"$ref": "#\/definitions\/scaMethod"
}
},
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"description": "Relative path to the endpoint to see the created signing basket",
"properties": {
"href": {
"type": "string",
"description": "Relative URL to resource",
"example": "\/signing-baskets\/{basketId}"
}
}
},
"startAuthorisationWithAuthenticationMethodSelection": {
"type": "object",
"description": "Relative path to the endpoint where an authorization can be initiated.",
"properties": {
"href": {
"type": "string",
"description": "Relative URL to resource",
"example": "\/signing-baskets\/{basketId}\/authorisations"
}
}
}
}
}
}
}
Describes an authorization-resource.
{
"type": "object",
"properties": {
"authorisationId": {
"type": "string",
"description": "GUID, reference to specific authorization resource",
"example": "ad155467-1505-41c9-9158-bc1811fc632b"
},
"basketId": {
"type": "string",
"description": "GUID, reference to the signing basket that is related to this authorisation.",
"example": "c57297dc-fa74-4cad-a328-40258ae7976f"
},
"chosenScaMethod": {
"$ref": "#\/definitions\/scaMethod"
},
"scaStatus": {
"type": "string",
"description": "Describes the status of the authorization event.\nscaMethodSelected -> indicates that no events have taken place since creating the authorization, started -> Signing is initialized and the PSU should sign, finalized -> Signing has finished succesfully, failed -> Signing has ended unsucessfully",
"enum": [
"scaMethodSelected",
"started",
"finalized",
"failed"
]
},
"paymentIds": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"STOHYD75412344553",
"STOHYD1515151515151"
]
},
"psuMessage": {
"type": "string",
"description": "Message for the Payment Signing User, included if an action needs to be taken by the user during a pending signing.",
"example": "Öppna Mobilt BankID app"
},
"tppMessages": {
"type": "array",
"description": "Message for the Third Party Provider, e.g. if an action needs to be taken by the user during a pending signing.",
"items": {
"type": "string",
"example": "Customer must open Mobile BankId application"
}
},
"_links": {
"type": "object",
"properties": {
"self": {
"type": "object",
"description": "Relative path to the endpoint to see the created authorization resource",
"properties": {
"href": {
"type": "string",
"description": "Relative URL to resource",
"example": "\/signing-baskets\/{basketId}\/authorisations\/{authorisationId}"
}
}
},
"scaRedirect": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "Redirect link to finish signing with Digipass",
"example": "https:\/\/notreal.sebgroup.com\/pss?authorisationId={authorisationId}"
}
}
}
}
}
}
}
{
"type": "object",
"properties": {
"authenticationMethodId": {
"type": "string",
"description": "Field with the correct SCA method to use for payment. Equivalent to authenticationMethodId field of SCAMethod shown.",
"example": "mobiltbankid"
}
}
}
{
"properties": {
"paymentId": {
"type": "string",
"description": "The id that SEB creates for the payment",
"example": "STOHYD01180208082256128737000001"
},
"transactionStatus": {
"type": "string",
"description": "Contains the current status of the payment.",
"enum": [
"RCVD",
"ACTC",
"CANC",
"RJCT"
]
},
"templateId": {
"type": "string",
"example": "swedish-domestic-private-bankgiros",
"description": "The templateId supplied at payment creation."
},
"remittanceInformationStructured": {
"description": "Used for OCR with bankgiro and postgiro.",
"type": "object",
"properties": {
"reference": {
"type": "string",
"description": "The structured remittance reference number for the payment.",
"example": "234634699"
},
"referenceType": {
"type": "string",
"description": "Type of reference number.",
"enum": [
"OCR"
]
}
}
},
"remittanceInformationUnstructured": {
"description": "Message field to creditor.",
"type": "string",
"maxLength": 100,
"example": "Liten drake"
},
"debtorAccountMessage": {
"description": "A message shown on debtor account statement.",
"type": "string",
"example": "Text for my payment"
},
"creditorAccountMessage": {
"description": "A message shown on creditor account statement. Only usable with some payment products.",
"type": "string",
"example": "Text to you"
},
"requestedExecutionDate": {
"type": "string",
"description": "Requested execution date of transaction in format yyyy-mm-dd. If the date is not a valid bank date for the payment product, then the payment will be rejected.",
"example": "2018-02-12"
},
"instructedAmount": {
"properties": {
"currency": {
"type": "string",
"example": "SEK"
},
"amount": {
"type": "number",
"example": 345.5
}
}
},
"debtorAccount": {
"properties": {
"iban": {
"description": "Debtor account number in IBAN format",
"type": "string",
"example": "SE8050000000052800025220"
}
}
},
"creditorAccount": {
"description": "Conditional, only a single property is set.",
"properties": {
"iban": {
"type": "string",
"example": "SE8050000000052800025220"
},
"bban": {
"type": "string",
"example": "52800025220"
},
"pgnr": {
"type": "string",
"example": "44580264"
},
"bgnr": {
"type": "string",
"example": "0001212121"
}
}
},
"creditorName": {
"description": "Name of pre registered creditor, needed for specific types of international payments.",
"type": "string",
"example": "Creditor Namesson"
},
"chosenScaMethod": {
"type": "object",
"description": "The selected Strong Customer Authentication method. This is shown after a SCA method has been selected.",
"items": {
"$ref": "#\/definitions\/scaMethod"
}
},
"_links": {
"type": "object",
"properties": {
"status": {
"type": "object",
"description": "Relative path to the endpoint to see the status of the payment initiation",
"properties": {
"href": {
"type": "string",
"description": "Relative URL to resource",
"example": "\/payments\/sepa-credit-transfers\/STOHYD01180208082256128737000001\/status"
}
}
}
}
}
}
}
{
"properties": {
"transactionStatus": {
"type": "string",
"description": "Contains the current status description of the payment.",
"enum": [
"RCVD",
"ACTC",
"CANC",
"RJCT"
],
"example": "ACTC"
},
"scaMethods": {
"type": "array",
"description": "Array containing names of available Strong Customer Authentication methods. These are only shown until a method is selected for a payment.",
"items": {
"$ref": "#\/definitions\/scaMethod"
}
},
"chosenScaMethod": {
"type": "object",
"description": "The selected Strong Customer Authentication method. This is shown after a SCA method has been selected.",
"items": {
"$ref": "#\/definitions\/scaMethod"
}
},
"scaStatus": {
"type": "string",
"description": "Describes the status of an ongoing authorization event linked to this payment, this will not be displayed for finalised or failed authorisations.\nscaMethodSelected -> indicates that no events have taken place since creating the authorization, started -> Signing is initialized and the PSU should sign, finalized -> Signing has finished succesfully, failed -> Signing has ended unsucessfully",
"enum": [
"scaMethodSelected",
"started",
"finalized",
"failed"
]
},
"psuMessage": {
"type": "string",
"description": "Message for the Payment Signing User, included if an action needs to be taken by the user during a pending signing.",
"example": "Öppna Mobilt BankID app"
},
"tppMessages": {
"type": "array",
"description": "Message for the Third Party Provider, e.g. if an action needs to be taken by the user during a pending signing or an error message.",
"items": {
"type": "string",
"example": "Customer must open Mobile BankId application"
}
},
"_links": {
"type": "object",
"properties": {
"startAuthorisationWithAuthenticationMethodSelection": {
"type": "object",
"description": "Relative path to the endpoint for selection of authentication method (using POST). Included only for payments without a set method.",
"properties": {
"href": {
"type": "string",
"description": "Relative URL to resource",
"example": "\/payments\/swedish-domestic-private-bankgiros\/STOHYD01180208082256128737000001\/authorisations"
}
}
}
}
}
}
}
{
"properties": {
"transactionStatus": {
"type": "string",
"description": "Contains the current status description of the payment.",
"enum": [
"RCVD",
"ACTC",
"CANC",
"RJCT"
],
"example": "ACTC"
},
"_links": {
"type": "object",
"properties": {
"status": {
"type": "object",
"description": "Relative path to the endpoint to see the status of the payment initiation",
"properties": {
"href": {
"type": "string",
"description": "Relative URL to resource",
"example": "\/payments\/sepa-credit-transfers\/STOHYD01180208082256128737000001\/status"
}
}
}
}
}
}
}
{
"type": "object",
"properties": {
"authenticationType": {
"type": "string",
"description": "Berlin group authentication type definition"
},
"authenticationMethodId": {
"type": "string",
"description": "Authentication method, this value should be sent as an input parameter to select SCA method.",
"example": "mobiltbankid"
},
"name": {
"type": "string",
"description": "Casual name of method."
},
"explanation": {
"type": "string",
"description": "Used to provide end-to-end identification for \"sepa-credit-transfers\" only."
}
}
}
Instruction for a payment type, fields are relevant only for specific payment types this should be checked in the template service.
{
"type": "object",
"properties": {
"templateId": {
"type": "string",
"description": "Optional field in input. If provided it needs to match product in path.",
"example": "swedish-domestic-private-bankgiros"
},
"endToEndIdentification": {
"type": "string"
},
"remittanceInformationStructured": {
"description": "Used for OCR with bankgiro and postgiro or SCOR with SEPA payments. If you provide this then omit remittanceInformationUnstructured.",
"type": "object",
"properties": {
"reference": {
"type": "string",
"description": "The structured remittance reference number for the payment.",
"example": "234634699"
},
"referenceType": {
"type": "string",
"description": "Type of reference number.",
"enum": [
"OCR",
"SCOR"
]
}
}
},
"remittanceInformationUnstructured": {
"description": "Message field to creditor.",
"type": "string",
"maxLength": 100,
"example": "Liten drake"
},
"debtorAccountMessage": {
"description": "A message shown on debtor account statement, max length depending on payment product",
"type": "string",
"example": "Text for my payment"
},
"creditorAccountMessage": {
"description": "A message shown on creditor account statement. Only usable with some payment products.",
"type": "string",
"example": "Text to you"
},
"requestedExecutionDate": {
"type": "string",
"description": "Requested execution date of transaction in format yyyy-mm-dd. If the date is not a valid bank date for the payment product, then the payment will be rejected.",
"example": "2018-02-12"
},
"instructedAmount": {
"properties": {
"currency": {
"type": "string",
"example": "SEK"
},
"amount": {
"type": "string",
"example": "345.50"
},
"equivalentAmount": {
"description": "Amount in SEK for non SEK account",
"type": "string",
"example": ""
}
},
"type": "object"
},
"debtorAccount": {
"properties": {
"iban": {
"description": "Debtor account number in IBAN format",
"type": "string",
"example": "SE8050000000052800025220"
},
"bban": {
"description": "Debtor account number in BBAN format, only for corporate payments.",
"type": "string",
"example": "52800025220"
}
},
"type": "object"
},
"creditorAccount": {
"description": "Conditional, only one of the properties may be used.",
"properties": {
"iban": {
"type": "string",
"example": "SE8050000000052800025220"
},
"bban": {
"type": "string",
"example": "52800025220"
},
"pgnr": {
"type": "string",
"example": "44580264"
},
"bgnr": {
"type": "string",
"example": "0001212121"
}
},
"type": "object"
},
"creditorAddress": {
"description": "Address fields can be added for some payment types. See each individual template.",
"properties": {
"street": {
"type": "string",
"example": "The Svedberg street 9999"
},
"country": {
"type": "string"
},
"city": {
"type": "string",
"example": "Stockholm"
},
"postalCode": {
"type": "string",
"example": "BE19271"
}
}
},
"creditorDetails": {
"description": "See specific payment types."
},
"bankCharges": {
"description": "See specific payment types.",
"type": "string"
},
"debtorReceipt": {
"type": "boolean",
"description": "Receipt can be requested for some payment types."
},
"instructionId": {
"description": "All fields after this are only relevant to corporate payments. The remitters own reference which will be stated in the transaction reporting by the bank in order to identify the transaction. It will not be forwarded to the beneficiary.",
"type": "string",
"example": "Payment info"
},
"chargeBearer": {
"description": "Charge sharing instructions for corporate payments.",
"type": "string",
"example": "DEBT"
},
"debtorAgentBic": {
"type": "string",
"example": "DEUTDEFFXXX"
},
"categoryPurpose": {
"type": "string",
"description": "Value to be used to determine if the payment is a Split payment (VATX) or a Tax payment (TAXS)"
},
"intermediaryAgentBic": {
"type": "string",
"example": "DEUTDEFFXXX"
},
"creditorAgentBic": {
"type": "string",
"example": "ESSESSESSXXX"
},
"creditorAgentOther": {
"type": "object",
"properties": {
"clearingSystemId": {
"type": "string",
"example": "“GBDSC”"
},
"memberId": {
"type": "string",
"example": "“404865”"
}
}
},
"regulatoryReporting": {
"type": "array",
"items": {
"type": "object",
"properties": {
"debitCreditReportingIndicator": {
"type": "string",
"example": "DEBT"
},
"reportingCode": {
"type": "string"
},
"reportingInformation": {
"type": "string"
}
}
}
}
}
}
When contacting customer support, please provide entire error structure.
{
"properties": {
"type": {
"description": "A URI reference that identifies the problem type.",
"example": "https:\/\/berlingroup.com\/error-codes\/RESOURCE_UNKNOWN",
"type": "string"
},
"title": {
"description": "Short human readable description of error type.",
"example": "The addressed resource is unknown relative to the TPP.",
"type": "string"
},
"detail": {
"description": "Detailed human readable text specific to this instance of the error.",
"example": "Debit account not found",
"type": "string"
},
"code": {
"description": "Message code to explain the nature of the underlying error.",
"example": "RESOURCE_UNKNOWN",
"type": "string"
}
}
}
- Terms and Conditions · Contact us here or at developerportal@seb.se