Settle API Reference

This is the reference documentation for the Settle API. The Settle API enables merchants to interact with Settle, registering POS, shortlinks for QR scans, payment requests, permission requests for end user info and more.

All endpoints are listed below, along with their expected input and output. The default content type for endpoints is application/vnd.mcash.api.merchant.v1+json.


Merchant

Endpoint for retrieving info about merchants

This endpoint supports retrieval of the information about a merchant that is mainly relevant to an integrator. Administration of the merchant resource is not part of the Merchant API as only the legal entity owning the merchant has access to do this using the SSP (Self Service Portal).

GET /merchant/<merchant_id>/

Required auth level: SECRET

Authorized roles: ALL

Get merchant info

Parameters:
  • merchant_id -- Merchant id assigned by Settle

Response schema

id : String : optional : default=null
Id
legal_entity : NdbKey : optional : default=null
Legal Entity
business_name : String : optional : default=null
Business Name
organization_id : String : optional : default=null
Organization Id
jurisdiction : String : optional : default=null
Jurisdiction
mcc : Integer : optional : default=null
Mcc
integrator : NdbKey : optional : default=null
Integrator
settlement_account : NdbKey : optional : default=null
Settlement Account
auth_duration : Integer : optional : default=null
Auth Duration
auto_release_after_auth_expire : Boolean : optional : default=null
Auto Release After Auth Expire
features[] : String : optional : default=null
Features
profile : MerchantProfileRegistration : optional : default=null
Profile
application : BusinessApplication : optional : default=null
Application
business_documents[] : BusinessDocument : optional : default=null
Business Documents
per_payment_amount_limit : MoneyInteger : optional : default=null
  • Optional
Per Payment Amount Limit
integration_type : String : optional : default=null
Integration Type
approved : Boolean : optional : default=null
Approved

Merchant lookup

Handle merchant lookup on secondary ID. This is endpoint can only be used by integrators.

GET /merchant_lookup/<lookup_id>/

Required auth level: OPEN

Authorized roles: ALL

Perform a Merchant Lookup.

User

In order to gain access to the Merchant API a client must authenticate itself using the ID and the secret/public key of an existing user. This means that the first user for a merchant must be created in the Self Service Portal or by an integrator on behalf of the merchant.

Each user is created for a specific merchant, which ID is given by the value of the X-Auka-Merchant header when making a create user request. A user can only interact with the API on behalf of the merchant which it was created for. The user ID is chosen on create and is has to be unique for the parent Merchant.

POST /user/

Required auth level: KEY

Authorized roles: ALL

Create user for the Merchant given in the X-Auka-Merchant header.

Request schema

id : String : optional : default=null
User id
netmask : String : optional : default=null
  • Optional
  • Valid netmask IP v 4 and 6
Limit user connections by netmask, for example 192.168.1.0/24
label : String : optional : default=null
User given name to RSA key/secret
secret : String : optional : default=null
  • Optional
  • 8 <= length <= 64
Secret used when authenticating with Settle
pubkey : PubKey : optional : default=null
  • Optional
RSA key used for authenticating by signing

Response schema

id : String : optional : default=null
User id
PUT /user/<user_id>/

Required auth level: KEY

Authorized roles: ALL

Update user

Request schema

netmask : String : optional : default=null
  • Optional
  • Valid netmask IP v 4 and 6
Limit user connections by netmask, for example 192.168.1.0/24
label : String : optional : default=null
User given name to RSA key/secret
secret : String : optional : default=null
  • Optional
  • 8 <= length <= 64
Secret used when authenticating with Settle
pubkey : PubKey : optional : default=null
  • Optional
RSA key used for authenticating by signing
DELETE /user/<user_id>/

Required auth level: KEY

Authorized roles: ALL

GET /user/<user_id>/

Required auth level: SECRET

Authorized roles: ALL

Get user info

Response schema

id : String : optional : default=null
User id
netmask : String : optional : default=null
  • Optional
  • Valid netmask IP v 4 and 6
Limit user connections by netmask, for example 192.168.1.0/24
label : String : optional : default=null
User given name to RSA key/secret
has_secret : Boolean : optional : default=null
Whether user has secret set
pubkey : PubKey : optional : default=null
  • Optional
RSA key if registered

Pos

The POS endpoint represents a Point Of Sale, managed by the merchant or integrator.

The POS can be physical, like a store till or a vending machine, it can represent a mobile app that moves around, a webshop or a server representing a poster. Defining the type can affect map representation in app.

POST /pos/

Required auth level: SECRET

Authorized roles: ALL

Create POS resource

Status Codes:
  • 201 -- POS created
  • 400 -- Bad request, validation error
Response Headers:
 
  • Location -- URI to POS resource GET /merchant/v1/pos/<pos_id>/

Request schema

name : String : required
  • length <= 100
  • Data required (new or existing on update)
Human-readable name of the POS, used for displaying payment request origin to end user
type : String : required
  • length <= 50
  • Value in store, webshop, mobile, vending, poster
  • Data required (new or existing on update)
POS type
location : Location : optional : default=null
Merchant location
id : String : required
  • Data required (new or existing on update)
  • length <= 100
The ID of the POS that is to be created. Has to be unique for the merchant

Response schema

id : String : optional : default=null
Id
GET /pos/

Required auth level: KEY

Authorized roles: ALL

List all Point of Sales for merchant

Response schema

uris[] : String : required
  • Data required (new or existing on update)
A list of absolute paths to the requested resources
next : String : optional : default=null
Path to the next list chunk
prev : String : optional : default=null
Path to the previous list chunk
PUT /pos/<pos_id>/

Required auth level: SECRET

Authorized roles: ALL

Update POS resource

Parameters:
  • pos_id -- POS id as chosen on registration
Status Codes:
  • 204 -- No content
  • 400 -- Bad request, validation error

Request schema

name : String : required
  • length <= 100
  • Data required (new or existing on update)
Human-readable name of the POS, used for displaying payment request origin to end user
type : String : required
  • length <= 50
  • Value in store, webshop, mobile, vending, poster
  • Data required (new or existing on update)
POS type
location : Location : optional : default=null
Merchant location
DELETE /pos/<pos_id>/

Required auth level: KEY

Authorized roles: ALL

Delete POS

Parameters:
  • pos_id -- POS id as chosen on registration
Status Codes:
  • 204 -- No content
GET /pos/<pos_id>/

Required auth level: SECRET

Authorized roles: ALL

Retrieve POS info

Parameters:
  • pos_id -- POS id as chosen on registration

Response schema

id : String : optional : default=null
Id
name : String : required
  • length <= 100
  • Data required (new or existing on update)
Human-readable name of the POS, used for displaying payment request origin to end user
type : String : required
  • length <= 50
  • Value in store, webshop, mobile, vending, poster
  • Data required (new or existing on update)
POS type
location : Location : optional : default=null
Merchant location

Payment request

Request a payment from a customer.

A payment request goes through several stages. After being registered, the customer can either reject or authorize. An authorization is valid for 3 days, but can be reauthorized before it expires to be valid for 3 new days. Once authorized, it can be captured to be included in the next settlement.

This resource replaces the 'sale_request', but as additional functionality for auth/capture.

POST /payment_request/

Required auth level: SECRET

Authorized roles: ALL

Post payment request.

The call is idempotent; that is, if one posts the same pos_id and pos_tid twice, only one payment request is created.

Parameters:
  • tid -- Transaction id assigned by Settle
Status Codes:
  • 200 -- OK, identical payment request already created
  • 201 -- OK, new payment request
  • 400 -- Bad request, validation error
  • 409 -- Conflict, same pos_id and pos_tid used for a different request earlier

Request schema

display_message_uri : String : optional : default=null
  • Optional
  • URL
Messages that can be used to inform the POS operator about the progress of the payment request will be POSTed to this URI if provided
callback_uri : String : optional : default=null
  • Optional
  • CallbackURI
If provided, Settle will POST to this URI when the status of the payment request changes, using the message mechanism described in the introduction. The data in the "object" part of the message is the same as what can be retrieved by calling GET on the "/payment_request/<tid>/outcome/" resource URI.
line_items[] : LineItem : optional : default=null
List of items in sale.
customer : PersonIdentifier : optional : default=null
  • Optional
  • length <= 100
Customer identifiers include None, msisdn, scan token, access token,shortlink_id:xxxx or shortlink_sn:xxxx.If not set (None), success_return_uri and failure_return_uri needs to be set.If not set (None), a uri to the checkout portal will be in the response.
max_scan_age : Integer : optional : default=60
  • Optional
  • 0 <= value <= 2592000
Used if customer is set to shortlink_id:xxxx or shortlink_sn:xxxx.Integer number of seconds.The payment request will be assigned to the scantoken created on the shortlink_idor shortlink_sn, no earlier then this number of seconds ago.
currency : Currency : required
  • Data required (new or existing on update)
  • length == 3
3 chars https://en.wikipedia.org/wiki/ISO_4217
amount : MoneyInteger : required
  • Data required (new or existing on update)
  • Positive
The base amount of the payment.
additional_amount : MoneyInteger : optional : default=0
  • NonNegative
Typically cash withdrawal or gratuity
additional_edit : Boolean : optional : default=false
Whether user is allowed to additional amount for gratuity or similar
allow_credit : Boolean : required
  • Input required
Whether to allow credit payment for this payment request. Credit incurs interchange
pos_id : String : required
  • Data required (new or existing on update)
  • length <= 64
  • Regexp: ^[a-zA-Z0-9_.-]+$
The POS this payment request originates from, used for informing user about origin
pos_tid : String : required
  • Data required (new or existing on update)
  • length <= 64
  • Regexp: ^[a-zA-Z0-9_.-]+$
Local transaction id for POS. This must be unique for the POS
text : String : optional : default=null
Text that is shown to user when asked to pay. This can contain linebreaks and the text has tofit on smartphones screens.
success_return_uri : String : optional : default=null
  • Optional
  • Regexp: (^|^w+://(localhost|[^/:]+|([0-9]{1,3}.){3}[0-9]{1,3})?(:[0-9]+)?)(/.*)?$
Return url if payment successful
failure_return_uri : String : optional : default=null
  • Optional
  • Regexp: (^|^w+://(localhost|[^/:]+|([0-9]{1,3}.){3}[0-9]{1,3})?(:[0-9]+)?)(/.*)?$
Return url if payment failed
cid : String : optional : default=null
Customer ID to be used for KID payments
links[] : PaymentRequestLink : optional : default=null
Links to be displayed for this payment request
action : String : required
  • Data required (new or existing on update)
  • Value in sale, auth, SALE, AUTH
Action to perform, the main difference is what it looks like in App UI.
expires_in : Integer : optional : default=21600
  • 0 <= value <= 2592000
Expiration in seconds from when server received request
required_scope : Scope : optional : default=null
  • Optional
Set this field to ask for data from the user together with the payment request.
required_scope_text : String : optional : default=null
  • Optional
  • length <= 150
Text that is shown to user when asked for permission.This can contain linebreaks and the text has to fit on smartphones screens.

Response schema

id : String : required
  • Data required (new or existing on update)
Transaction id
uri : String : optional : default=null
  • Optional
  • URL
If payment request was posted without a customer, user can claim it on this uri
GET /payment_request/

Required auth level: SECRET

Authorized roles: ALL

Request schema

created_from : DateTime : optional : default=null
Created From
created_to : DateTime : optional : default=null
Created To
cursor : Cursor : optional : default=null
Cursor
page_size : Integer : optional : default=100
Page Size
only_ok : Boolean : optional : default=false
Only Ok
status : SelectMultiple : optional : default=null
Status

Response schema

items[] : PaymentRequestListItem : optional : default=null
Items
cursor : Cursor : optional : default=null
Cursor
PUT /payment_request/<tid>/

Required auth level: SECRET

Authorized roles: ALL

Update payment request, reauthorize, capture, release or abort

Capturing an authorized payment or reauthorizing is done with the action field.

The call is idempotent; that is, if one posts the same amount, additional_amount and capture_id twice with action CAPTURE, only one capture is performed. Similarly, if one posts twice with action CAPTURE without any amount stated, to capture the full amount, only one full capture is performed.

Note that the REFUND action will require that the API call is made with the KEY authorization mode, not SECRET.

Parameters:
  • tid -- Transaction id assigned by Settle
Status Codes:
  • 204 -- OK (no content)
  • 400 -- Illegal input
  • 409 -- Illegal action at this time (capture before authorization, abort after capture)

Request schema

display_message_uri : String : optional : default=null
  • Optional
  • URL
Messages that can be used to inform the POS operator about the progress of the payment request will be POSTed to this URI if provided
callback_uri : String : optional : default=null
  • Optional
  • CallbackURI
If provided, Settle will POST to this URI when the status of the payment request changes, using the message mechanism described in the introduction. The data in the "object" part of the message is the same as what can be retrieved by calling GET on the "/payment_request/<tid>/outcome/" resource URI.
line_items[] : LineItem : optional : default=null
List of items in sale.
action : String : optional : default=null
  • Optional
  • Value in reauth, capture, abort, release, refund (case insensitive)
Action to perform
amount : MoneyInteger : optional : default=null
  • Ignored unless capture_id, refund_id
  • Ignored unless action is capture, refund
  • NonNegative
Use together with CAPTURE or REFUND actions to enable partial capture or refund, respectively. If set, additional_amount, currency and either of capture_id or refund_id must also be set. If all these four fields are unset, the full authorized amount will be captured on CAPTURE.
additional_amount : MoneyInteger : optional : default=null
  • Ignored unless capture_id, refund_id
  • Ignored unless action is capture, refund
  • NonNegative
Part of the additional amount to capture/refund. Must be set if amount is set, otherwise additional_amount must be unset.
capture_id : String : optional : default=null
  • Ignored unless action is capture
  • Required if amount, additional_amount, currency are set
  • Regexp: ^[a-zA-Z0-9_.-]+$
Local id for capture. Must be set if amount is set, otherwise capture_id must be unset.
refund_id : String : optional : default=null
  • Ignored unless action is refund
  • Required if amount, additional_amount, currency are set
  • Regexp: ^[a-zA-Z0-9_.-]+$
Local id for refund. Must be set if amount is set, otherwise capture_id must be unset.
currency : Currency : optional : default=null
  • Ignored unless capture_id, refund_id
  • Ignored unless action is capture, refund
  • length == 3
3 chars https://en.wikipedia.org/wiki/ISO_4217 . Required if the amount and additional_amount fields are set
text : String : optional : default=null
  • Optional
Text that is shown to user upon a refund. This can contain linebreaks and the text has to fit on smartphones screens.
GET /payment_request/<tid>/

Required auth level: SECRET

Authorized roles: ALL

Retrieve payment request info

Parameters:
  • tid -- Transaction id assigned by Settle

Response schema

id : String : required
  • Data required (new or existing on update)
Transaction id
uri : String : optional : default=null
  • Optional
  • URL
If payment request was posted without a customer, user can claim it on this uri
display_message_uri : String : optional : default=null
  • Optional
  • URL
Messages that can be used to inform the POS operator about the progress of the payment request will be POSTed to this URI if provided
callback_uri : String : optional : default=null
  • Optional
  • CallbackURI
If provided, Settle will POST to this URI when the status of the payment request changes, using the message mechanism described in the introduction. The data in the "object" part of the message is the same as what can be retrieved by calling GET on the "/payment_request/<tid>/outcome/" resource URI.
line_items[] : LineItem : optional : default=null
List of items in sale.
customer : PersonIdentifier : optional : default=null
  • Optional
  • length <= 100
Customer identifiers include None, msisdn, scan token, access token,shortlink_id:xxxx or shortlink_sn:xxxx.If not set (None), success_return_uri and failure_return_uri needs to be set.If not set (None), a uri to the checkout portal will be in the response.
max_scan_age : Integer : optional : default=60
  • Optional
  • 0 <= value <= 2592000
Used if customer is set to shortlink_id:xxxx or shortlink_sn:xxxx.Integer number of seconds.The payment request will be assigned to the scantoken created on the shortlink_idor shortlink_sn, no earlier then this number of seconds ago.
currency : Currency : required
  • Data required (new or existing on update)
  • length == 3
3 chars https://en.wikipedia.org/wiki/ISO_4217
amount : MoneyInteger : required
  • Data required (new or existing on update)
  • Positive
The base amount of the payment.
additional_amount : MoneyInteger : optional : default=0
  • NonNegative
Typically cash withdrawal or gratuity
additional_edit : Boolean : optional : default=false
Whether user is allowed to additional amount for gratuity or similar
pos_id : String : required
  • Data required (new or existing on update)
  • length <= 64
  • Regexp: ^[a-zA-Z0-9_.-]+$
The POS this payment request originates from, used for informing user about origin
pos_tid : String : required
  • Data required (new or existing on update)
  • length <= 64
  • Regexp: ^[a-zA-Z0-9_.-]+$
Local transaction id for POS. This must be unique for the POS
text : String : optional : default=null
Text that is shown to user when asked to pay. This can contain linebreaks and the text has tofit on smartphones screens.
success_return_uri : String : optional : default=null
  • Optional
  • Regexp: (^|^w+://(localhost|[^/:]+|([0-9]{1,3}.){3}[0-9]{1,3})?(:[0-9]+)?)(/.*)?$
Return url if payment successful
failure_return_uri : String : optional : default=null
  • Optional
  • Regexp: (^|^w+://(localhost|[^/:]+|([0-9]{1,3}.){3}[0-9]{1,3})?(:[0-9]+)?)(/.*)?$
Return url if payment failed
cid : String : optional : default=null
Customer ID to be used for KID payments
links[] : PaymentRequestLink : optional : default=null
Links to be displayed for this payment request
date_expires : DateTime : optional : default=null
Expiration date (for the original payment request; does not consider payment authorizations; see /outcome for that)
required_scope : String : optional : default=null
Set this field to ask for data from the user together with the payment request.
allow_credit : Boolean : optional : default=null
Whether to allow credit payment for this payment request. Credit incurs interchange

Outcome

The outcome endpoint shows the outcome info for a payment request, reauth or capture.

This endpoints includes specified fee and/or interchange that will be deducted from payout, and also updated additional amount field if the user added gratuity.

If the callback uri registered for the payment request was secure (https), the contents of this form was sent along with the callback. If the callback uri was insecure, a notification pointing to this endpoint was sent instead.

The status field contains a simple string that is one of ok, fail, auth, or pending. The status_code field contains more information. The codes currently documented are:

Code Reason status field
1003 PENDING - Waiting for customer or bank pending
2000 OK - Payment received ok
3008 AUTH - Payment authorized, ready for capture auth
4004 NOT_FOUND - No such customer fail
4019 ABORTED - Merchant aborted payment before capture fail
5006 REJECTED - Customer rejected/aborted payment request fail
5011 REQUEST_EXPIRED - Payment request expired fail
5012 AUTH_EXPIRED - Authorization not captured within 3 days fail

Note

The list of status codes may grow in the future, and API clients should deal with unknown status codes gracefully. However, one can rely on 1xxx and 3xxx being temporary states (merchant should wait for further updates), 2xxx represent final successful outcomes, and 4xxx and 5xxx represents final failure outcomes.

GET /payment_request/<tid>/outcome/

Required auth level: SECRET

Authorized roles: ALL

Retrieve payment request outcome

Parameters:
  • tid -- Transaction id assigned by Settle
Status Codes:
  • 200 -- OK
  • 404 -- tid not found (or unauthorized for this merchant)

Response schema

currency : Currency : required
  • Data required (new or existing on update)
  • length == 3
3 chars https://en.wikipedia.org/wiki/ISO_4217
amount : MoneyInteger : optional : default=null
Amount
additional_amount : MoneyInteger : optional : default=null
Additional amount might have been changed by user if additional_edit was true
auth_amount : MoneyInteger : optional : default=null
The authorized amount. If doing partial captures, this will show the amount still available in the authorization for subsequent captures; auth_amount = amount - sum(captured amounts)
auth_additional_amount : MoneyInteger : optional : default=null
The authorized additional amount. If doing partial captures, this will show the part of additional amount still available in the authorization for subsequent captures; auth_additional_amount = additional_amount - sum(captured additional amounts)
captures[] : Capture : optional : default=null
List of captures.
refunds[] : Refund : optional : default=null
List of refunds.
status : String : optional : default=null
  • Value in ok, fail, auth, pending
Payment request status (see above)
status_code : Integer : optional : default=null
Payment request status code (see above).
customer : PersonIdentifier : optional : default=null
Customer identifier as originally registered by POS.
date_modified : DateTime : optional : default=null
Last modified date
date_expires : DateTime : optional : default=null
Expiration date for current status. After a payment authorization is given this may extend beyond the original expiry date given in the payment request. An authorization expires after 3 days. When the payment request expires it is marked as failed (whether in pending or authorized state).
credit : Boolean : optional : default=false
Whether the received payment was a credit payment.
interchange_fee : MoneyInteger : optional : default=null
Interchange fee to be deducted if credit payment.
transaction_fee : MoneyInteger : optional : default=null
Transaction fee to be deducted.
attachment_uri : String : optional : default=null
  • Optional
  • URL
Endpoint for Attachment uploads, such as electronic receipts. This URI has a limited time to live, and a new URI is generated each time outcome is retrieved.
pos_id : String : required
  • Data required (new or existing on update)
The POS this request originates from, used for informing user about origin
pos_tid : String : required
  • Data required (new or existing on update)
  • length <= 64
  • Regexp: ^[a-zA-Z0-9_.-]+$
Local transaction id for POS. This must be unique for the POS
tid : String : required
  • Data required (new or existing on update)
  • length <= 64
  • Regexp: ^[a-zA-Z0-9_.-]+$
Settle transaction id
permissions : AccessTokenResponse : optional : default=null
If payment request was combined with a permission request, this field will contain the permission request outcome. Same as returned by a GET the permission request outcome endpoint

Sales summary

Get a sales summary report

GET /sales_summary/

Required auth level: SECRET

Authorized roles: ALL

Retrieve sales report

Request schema

from_date : Date : required
  • Input required
From Date
to_date : Date : optional : default=null
To Date
merchant_time : Boolean : optional : default=null
Merchant Time
frequency : Select : optional : default=null
Frequency

Response schema

merchant_timezone : String : optional : default=null
Merchant Timezone
result_timezone : String : optional : default=null
Result Timezone
start_of_day : Time : optional : default=null
Start Of Day
periods[] : DateTime : optional : default=null
Periods
data_until : DateTime : optional : default=null
Data Until
products[] : SalesSummaryProduct : optional : default=null
Products
max_timestamp : DateTime : optional : default=null
Max Timestamp

Last settlement

This endpoint redirects to the last Settlement.

Whenever a new Settlement is generated, this reference is automatically updated.

GET /last_settlement/

Required auth level: SECRET

Authorized roles: ALL

Redirect latest Settlement

Status Codes:
  • 302 -- Temporary redirect to the last settlement
  • 404 -- No settlements (none has been created yet)
Response Headers:
 
  • Location -- URI to last settlement

Settlement

Settle automatically generates settlements at regular intervals specified in the merchant agreement.

GET /settlement/

Required auth level: SECRET

Authorized roles: ALL

List settlements.

Response schema

uris[] : String : required
  • Data required (new or existing on update)
A list of absolute paths to the requested resources
next : String : optional : default=null
Path to the next list chunk
prev : String : optional : default=null
Path to the previous list chunk
GET /settlement/<settlement_id>/

Required auth level: SECRET

Authorized roles: ALL

Retrieve information regarding one settlement. The settlement contains detailed information about the amount paid out in the payout_details form. In case merchant has unsettled fees from previous settlements, Settle will attempt to settle these before paying out. If there are still unsettled fees after settlement is done, this amount will be transferred to the next settlement, or billed by Settle.

Parameters:
  • settlement_id -- The ID of the settlement to retrieve.
Status Codes:
  • 200 -- OK
  • 404 -- No settlement with this ID

Response schema

id : String : required
  • Data required (new or existing on update)
The ID of the settlement.
date_created : DateTime : required
  • Data required (new or existing on update)
The time that the settlement was generated.
transaction_log_uris[] : String : required
  • Data required (new or existing on update)
  • Regexp: (^|^w+://(localhost|[^/:]+.[a-z]{2,10}|([0-9]{1,3}.){3}[0-9]{1,3})(:[0-9]+)?)(/.*)?$
List of download URIs for the Transaction log blob object in CSV format.The Transaction log is divided in sizable chunks, and each URI points to its own chunk.
scope_log_uris[] : String : required
  • Data required (new or existing on update)
  • Regexp: (^|^w+://(localhost|[^/:]+.[a-z]{2,10}|([0-9]{1,3}.){3}[0-9]{1,3})(:[0-9]+)?)(/.*)?$
List of download URI`s for the Scope log blob object in CSV format. The Scope log is divided in sizable chunks, and each URI points to its own chunk.
settlement_summary : ReportSummary : optional : default=null
A Settlement Summary summarizes the set of transactions contained in the Settlement.All transactions are of the same currency. See: Settlement Summary.
payout_details : PayoutDetail : optional : default=null
Payout details

Settlement account

Handles retrieval of SettlementAccount

PUT /settlement_account/<settlement_account_id>/

Required auth level: SECRET

Authorized roles: ALL

Updates a SettlementAccount

Request schema

payout_account : String : required
  • Input required
Payout Account
frequency : SettlementAccountFrequency : optional : default=null
Frequency
GET /settlement_account/<settlement_account_id>/

Required auth level: SECRET

Authorized roles: ALL

Gets a SettlementAccount by ID.

Response schema

id : String : optional : default=null
Id
start_of_day : Time : optional : default=null
Start Of Day
currency : String : optional : default=null
Currency
payout_delay : TimeDelta : optional : default=null
Payout Delay
payout_account : String : optional : default=null
Payout Account
frequency : SettlementAccountFrequency : optional : default=null
Frequency

Settlement report

Handler for listing MerchantSettlements with a summary for reports

GET /settlement_report/

Required auth level: SECRET

Authorized roles: ALL

Endpoint accepts arguments for filtering the list of settlements and can omit empty settlements

Request schema

created_from : DateTime : optional : default=null
Created From
created_to : DateTime : optional : default=null
Created To
non_empty_only : Boolean : optional : default=false
Non Empty Only

Response schema

items[] : SettlementListItem : optional : default=null
Items
summary : SettlementListSummary : optional : default=null
Summary
report_context : SettlementListReportContext : optional : default=null
Report Context

Permission request

Request authorization to access user controlled endpoint.

POST /permission_request/

Required auth level: SECRET

Authorized roles: ALL

Permission request

The call is idempotent; that is, if one posts the same pos_id and pos_tid twice, only one Permission request is created.

Status Codes:
  • 200 -- OK, identical permission request already created
  • 201 -- Permission request created
  • 400 -- Bad request, validation error
Response Headers:
 
  • Location -- URI to permission request

Request schema

customer : PersonIdentifier : required
  • Data required (new or existing on update)
  • length <= 100
Typically scan token, msisdn or access token from permission request
pos_id : String : required
  • Data required (new or existing on update)
  • length <= 64
  • Regexp: ^[a-zA-Z0-9_.-]+$
The POS this permission request originates from, used for informing user about origin
pos_tid : String : required
  • Data required (new or existing on update)
  • length <= 64
  • Regexp: ^[a-zA-Z0-9_.-]+$
Local transaction id for POS. This must be unique for the POS
text : String : optional : default=null
Text that is shown to user when asked for permission. This can contain linebreaks and the text has to fit on smartphones screens.
callback_uri : String : optional : default=null
  • Optional
  • CallbackURI
If provided, Settle will POST to this URI when the status of the permission request changes. The data transferred in the POST are the same as what can be retrieved by calling GET on the resource URI.
scope : String : required
  • Data required (new or existing on update)
Space-delimited list of scopes. Any of: "openid" (static id, "address" (user preferred address), "profile" (name), "phone", "email", "shipping_address", "fodselsnummer"
expires_in : Integer : optional : default=21600
  • 0 <= value <= 2592000
Expiration in seconds from when server received request

Response schema

id : String : optional : default=null
Permission request id
GET /permission_request/<rid>/

Required auth level: SECRET

Authorized roles: ALL

See permission request info

Parameters:
  • rid -- Permission request id assigned by Settle

Response schema

customer : PersonIdentifier : required
  • Data required (new or existing on update)
  • length <= 100
Typically scan token, msisdn or access token from permission request
pos_id : String : required
  • Data required (new or existing on update)
  • length <= 64
  • Regexp: ^[a-zA-Z0-9_.-]+$
The POS this permission request originates from, used for informing user about origin
pos_tid : String : required
  • Data required (new or existing on update)
  • length <= 64
  • Regexp: ^[a-zA-Z0-9_.-]+$
Local transaction id for POS. This must be unique for the POS
text : String : optional : default=null
Text that is shown to user when asked for permission. This can contain linebreaks and the text has to fit on smartphones screens.
callback_uri : String : optional : default=null
  • Optional
  • CallbackURI
If provided, Settle will POST to this URI when the status of the permission request changes. The data transferred in the POST are the same as what can be retrieved by calling GET on the resource URI.
scope : String : required
  • Data required (new or existing on update)
Space-delimited list of scopes. Any of: "openid" (static id, "address" (user preferred address), "profile" (name), "phone", "email", "shipping_address", "fodselsnummer"
date_expires : DateTime : optional : default=null
Expiration date

Merchant ssp user

Handler for creating and retrieving MerchantSspUsers.

POST /merchant_ssp_user/

Required auth level: SECRET

Authorized roles: ALL

Creates a MerchantSspUser and returns 201 CREATED (unless a user with the same email already exists, which results in a 409 CONFLICT response)

Request schema

email : String : required
  • Email (regexp: ^.+@[^.].*.[a-z]{2,10}$)
  • Input required
Email
phone : String : optional : default=null
Phone
name : Name : optional : default=null
Name

Response schema

id : String : optional : default=null
Id
email : String : optional : default=null
  • Email (regexp: ^.+@[^.].*.[a-z]{2,10}$)
Email
phone : String : optional : default=null
Phone
name : NameResponse : optional : default=null
Name
legal_entities[] : NdbKey : optional : default=null
Legal Entities
bankid : String : optional : default=null
Bankid
DELETE /merchant_ssp_user/<merchant_ssp_user_id>/

Required auth level: SECRET

Authorized roles: ALL

Deletes a MerchantSspUser and returns 204 NO CONTENT

Currently only deletes if MerchantSspUser does not have any LegalEntities to avoid side effects Used to avoid inconsistencies between core and merchant console

GET /merchant_ssp_user/<merchant_ssp_user_id>/

Required auth level: SECRET

Authorized roles: ALL

Gets a MerchantSspUser

Response schema

id : String : optional : default=null
Id
email : String : optional : default=null
  • Email (regexp: ^.+@[^.].*.[a-z]{2,10}$)
Email
phone : String : optional : default=null
Phone
name : NameResponse : optional : default=null
Name
legal_entities[] : NdbKey : optional : default=null
Legal Entities
bankid : String : optional : default=null
Bankid

Outcome

When a user has accepted the permission request, the token data is sent to callback_uri, and is also available at this endpoint.

GET /permission_request/<rid>/outcome/

Required auth level: SECRET

Authorized roles: ALL

See outcome of permission request

Parameters:
  • rid -- Permission request id assigned by Settle

Response schema

access_token : String : optional : default=null
  • Optional
Access token
id_token : String : optional : default=null
  • Optional
A JWT that contains identity information about the user that is digitally signed by Settle
token_type : String : required
  • Data required (new or existing on update)
Type of access token, at this time it will always be Bearer
expires_in : Integer : optional : default=null
  • Optional
Lifetime in seconds of the access token
refresh_token : String : optional : default=null
  • Optional
Refresh token used to issue new access token after expiration
scope : String : optional : default=null
  • Optional
  • Value in address, bankid, email, fodselsnummer, openid, phone, profile, shipping_address
Space-delimited list of scopes. Any of: "openid" (static id, "address" (user preferred address), "profile" (name), "phone", "email", "shipping_address", "fodselsnummer"
currency : Currency : optional : default=null
  • Optional
  • length == 3
Currency for fee
transaction_fee : MoneyInteger : optional : default=null
Permission fee to be deducted from settlement
status : String : optional : default=null
Permission request status
status_code : Integer : optional : default=null
Permission request status code
pos_id : String : required
  • Data required (new or existing on update)
  • length <= 64
  • Regexp: ^[a-zA-Z0-9_.-]+$
The POS this request originates from, used for informing user about origin
pos_tid : String : required
  • Data required (new or existing on update)
  • length <= 64
  • Regexp: ^[a-zA-Z0-9_.-]+$
Local transaction id for POS. This must be unique for the POS
rid : String : required
  • Data required (new or existing on update)
Settle request id
user_info : Json : optional : default=null
User Info

Status code

Some resources, such as the outcome resources (for payment request and permission request), have a status code field in the response body. The status_code resource lists and describes all possible status codes. Making a GET /status_code/ request yields a list of status codes with corresponding names and descriptions. Making a GET /status_code/<value>/ request (substituting <value> for a status code integer) yields the information for a particular status code.

GET /status_code/

Required auth level: OPEN

Authorized roles: ALL

Response schema

A list of objects containing the following data

code : String : optional : default=null
Code
name : String : optional : default=null
Name
GET /status_code/<value>/

Required auth level: OPEN

Authorized roles: ALL

Response schema

code : String : optional : default=null
Code
name : String : optional : default=null
Name