Merchant API Reference¶

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 mCASH

Response schema

jurisdiction : String : required Data required (new or existing on update) length == 2	Jurisdiction
organization_id : String : required Data required (new or existing on update) length <= 100	National ID for the company owning the Merchant
business_name : String : required Data required (new or existing on update) length <= 100	Business Name
mcc : Integer : optional : default=0 Optional 0 <= value <= 9999	Merchant Category Code
netmask : String : optional : default=null Optional Valid netmask IP v 4 and 6	Limit POS connections for merchant by netmask, for example 192.168.1.0/24
location : Location : optional : default=null	Merchant location
id : String : optional : default=null	Id
settlement_account_id : String : optional : default=null	The settlement account ID for the merchant. This will show up in the bank transcripts.
profile : MerchantProfile : optional : default=null	Merchant profile

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-Mcash-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: SUPERUSER, INTEGRATOR

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

Request schema

id : String : required Data required (new or existing on update)	User id
roles[] : String : optional : default=null Value in user, superuser (case insensitive)	Role
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
secret : String : optional : default=null Optional 8 <= length <= 64	Secret used when authenticating with mCASH
pubkey : PubKey : optional : default=null Optional	RSA key used for authenticating by signing

Response schema

id : String : required Data required (new or existing on update)

User id

PUT /user/<user_id>/¶

Required auth level: SECRET

Authorized roles: SUPERUSER, INTEGRATOR

Update user

Request schema

roles[] : String : optional : default=null Value in user, superuser (case insensitive)	Role
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
secret : String : optional : default=null Optional 8 <= length <= 64	Secret used when authenticating with mCASH
pubkey : PubKey : optional : default=null Optional	RSA key used for authenticating by signing

GET /user/<user_id>/¶

Required auth level: SECRET

Authorized roles: ALL

Get user info

Response schema

id : String : required Data required (new or existing on update)	User id
roles[] : String : optional : default=null Value in user, superuser (case insensitive)	Role
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
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: USER, SUPERUSER, INTEGRATOR

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: SECRET

Authorized roles: SUPERUSER, INTEGRATOR

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: USER, SUPERUSER, INTEGRATOR

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: SECRET

Authorized roles: SUPERUSER, INTEGRATOR

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: USER, SUPERUSER, INTEGRATOR

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 ledger report and 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 mCASH
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

ledger : String : optional : default=null Optional	Log entries will be added to the open report on the specified ledger. If this argument is not provided, the payment will not be logged on a ledger (but is available in settlement reports).
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, mCASH 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 : Money : required Data required (new or existing on update) Positive	The base amount of the payment.
additional_amount : Money : 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)	The POS this payment request originates from, used for informing user about origin
pos_tid : String : required Data required (new or existing on update)	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: (^|^[a-z]+://([^/:]+|([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: (^|^[a-z]+://([^/:]+|([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	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

PUT /payment_request/<tid>/¶

Required auth level: SECRET

Authorized roles: ALL

Update payment request, reauthorize, capture, release or abort

It is possible to update ledger and the callback URIs for a payment request. Changes are appended to the open report of a ledger (if ledger is specified), and notifications are sent to the callback registered at the time of notification.

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 mCASH
Status Codes:	204 -- OK (no content) 400 -- Illegal input 409 -- Illegal action at this time (capture before authorization, abort after capture)

Request schema

ledger : String : optional : default=null Optional	Log entries will be added to the open report on the specified ledger. If this argument is not provided, the payment will not be logged on a ledger (but is available in settlement reports).
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, mCASH 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 : Money : optional : default=null Ignored unless action is capture, refund Required if capture_id, refund_id are set 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 : Money : optional : default=0 Ignored unless action is capture, refund NonNegative Required if capture_id, refund_id are set	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 action is capture, refund Required if capture_id, refund_id are set 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 mCASH

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
ledger : String : optional : default=null Optional	Log entries will be added to the open report on the specified ledger. If this argument is not provided, the payment will not be logged on a ledger (but is available in settlement reports).
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, mCASH 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 : Money : required Data required (new or existing on update) Positive	The base amount of the payment.
additional_amount : Money : 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)	The POS this payment request originates from, used for informing user about origin
pos_tid : String : required Data required (new or existing on update)	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: (^|^[a-z]+://([^/:]+|([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: (^|^[a-z]+://([^/:]+|([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)
allow_credit : Boolean : optional : default=null	Whether to allow credit payment for this payment request. Credit incurs interchange
required_scope : String : optional : default=null Optional	Set this field to ask for data from the user together with the payment request.

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:

GET /payment_request/<tid>/outcome/¶

Required auth level: SECRET

Authorized roles: ALL

Retrieve payment request outcome

Parameters:	tid -- Transaction id assigned by mCASH
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 : Money : optional : default=null	Amount
additional_amount : Money : optional : default=null	Additional amount might have been changed by user if additional_edit was true
auth_amount : Money : 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 : Money : 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 : Money : optional : default=null	Interchange fee to be deducted if credit payment.
transaction_fee : Money : optional : default=null	Transaction fee to be deducted.
report_id : String : optional : default=null	The Report that this transaction is included in.
report_uri : String : optional : default=null Optional URL	Endpoint for the report that contains the current state of the payment request.
ledger : String : optional : default=null Optional	ID of ledger this payment request is included in
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)	Local transaction id for POS. This must be unique for the POS
tid : String : required Data required (new or existing on update)	mCASH 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

Shortlink¶

Shortlink scan handler.

When user scans, mCASH sends scan id and argstring, and can receive text and uri which can be transported back to the app. Uri will be opened in a web view inside the app if registered in list of trusted domains.

POST http://merchant.server/callback/url¶

Request schema

id : String : required Data required (new or existing on update)	The scan token ID that can be used as recipient for payment and permission requests. Expires in one day.
argstring : String : optional : default=null	The string that was appended to the shortlink value in the QR code that was scanned

Response schema

text : String : optional : default=null Optional	Text that will be displayed to user. This stays on screen until user acknowledges reading it.
uri : String : optional : default=null Optional URL	URI to open in mCASH App.

Ledger¶

A Ledger contains reports.

A Merchant has by default one Ledger, but more can be created - for example one per POS or one per employee. If none are created all payments are associated with the default Ledger.

PUTing to an endpoint of an open report will close the report and the server will respond with status code 200 OK. If the report is already closed, no changes are made to the report, but the server will still respond with 200 OK.

Multi currency support: The Merchant can request payments in any currency by having one Ledger per currency. See the currency field below.

POST /ledger/¶

Required auth level: SECRET

Authorized roles: ALL

Create a Ledger.

Status Codes:	201 -- Created 400 -- Bad request, validation error
Response Headers:
	Location -- URI to POS resource GET /merchant/v1/ledger/<ledger_id>/

Request schema

currency : String : required Data required (new or existing on update)	Currency of all the transactions contained in this Ledger.
description : String : optional : default=null	Human-readable description of Ledger

Response schema

id : String : required Data required (new or existing on update)

Ledger id.

GET /ledger/¶

Required auth level: SECRET

Authorized roles: ALL

List available ledgers

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 /ledger/<ledger_id>/¶

Required auth level: SECRET

Authorized roles: ALL

Update Ledger info

Parameters:	ledger_id -- Ledger id assigned by mCASH
Status Codes:	204 -- No content

Request schema

description : String : optional : default=null

Description of the Ledger, and usage.

DELETE /ledger/<ledger_id>/¶

Required auth level: SECRET

Authorized roles: ALL

Disable ledger. It will still be used for payments that are currently in progress, but it will not be possible to create new payments with the ledger.

Parameters:	ledger_id -- Ledger id assigned by mCASH
Status Codes:	204 -- No content 409 -- Conflict (tried to delete built-in 'default' ledger)

GET /ledger/<ledger_id>/¶

Required auth level: SECRET

Authorized roles: ALL

Get Ledger info

Parameters:	ledger_id -- Ledger id assigned by mCASH

Response schema

id : String : required Data required (new or existing on update)	Ledger id.
currency : String : required Data required (new or existing on update)	Currency of all the transactions contained in this Ledger.
description : String : optional : default=null	Human-readable description of Ledger
open_report_uri : String : optional : default=null Optional URL	URI of the currently open Report.if there is no open Report, this field is null
last_closed_report_uri : String : optional : default=null Optional URL	URI of the last closed Report in the Transaction Log. If there is no previous Report, this field is null.

Report¶

Endpoint for Reports.

The transactions in a Ledger are grouped into Reports. These Reports are collections of transactions that are to be reconciled as a group. At any one time there is only one open Report for each Ledger, and new transactions that are added to the Ledger are appended to the open Report.

The Report holds a list of transactions that both the Merchant and mCASH must agree upon prior to reconciliation.

The report can be closed (See: PUT), making it an immutable historical entry that can be used for reconciliation.

A summary of a closed Report is found in the report_summary field.

For more information see ledgers-reports-settlements.

GET /ledger/<ledger_id>/report/¶

Required auth level: SECRET

Authorized roles: ALL

List reports on the given ledger.

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 /ledger/<ledger_id>/report/<report_id>/¶

Required auth level: SECRET

Authorized roles: ALL

Close Report

When you PUT to a report, it will start the process of closing it. When the closing process is complete (i.e. when report.status == 'closed') mCASH does a POST call to callback_uri, if provided. This call will contain JSON data similar to when GETing the Report.

Closing a report automatically open a new one.

The contents of a GET /merchant/v1/ledger/<ledger_id>/report/<report_id>/ is included in callback if callback is a secure URI, otherwise the link itself is sent in callback.

Parameters:	ledger_id -- Id for ledger for report report_id -- Report id assigned by mCASH
Status Codes:	204 -- No content

Request schema

callback_uri : String : optional : default=null Optional CallbackURI

Callback URI to be called when Report has finished closing.

GET /ledger/<ledger_id>/report/<report_id>/¶

Required auth level: SECRET

Authorized roles: ALL

Get Report info

Response schema

transaction_log_uris[] : String : optional : default=null	List of download URI`s for the Transaction log blob object (typically in CSV format.) The Transaction log is divided in sizable chunks, and each URI points to its own chunk. Only present if the Report is closed.
scope_log_uris[] : String : optional : default=null Regexp: (^|^[a-z]+://([^/:]+.[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 (typically in CSV format.) The Scope log is divided in sizable chunks, and each URI points to its own chunk. Only present if the Report is closed.Just like each element in the Transaction log associated is with a Payment request, each element in the Scopes log is associated with a Permission request.
previous_report_uri : String : optional : default=null Optional URL	URI of the last closed Report in the Transaction Log. If there is no previous Report, this field is null.
settlement_uri : String : optional : default=null Optional	DEPRECATED, DO NOT USE. Will always be null.
status : String : optional : default=null Value in open, closing, closed	The status of the Report.
time_closed : DateTime : optional : default=null	The time that the Report was closed. If the Report is not closed, this field is null.
report_summary : ReportSummary : optional : default=null	A Report Summary summarizes the set of transactions contained in the Report.All transactions are of the same currency. null unless the Report is closed. See: Report Summary.
callback_uri : String : optional : default=null Optional CallbackURI	Callback URI to be called when Report had finished closing.
payment_request_count : Integer : optional : default=null Optional	The number of payment requests made during the time span of this report on this ledger (number of "pending" in transaction log)
payment_auth_count : Integer : optional : default=null Optional	The number of payment authorizations granted during the time span of this report on this ledger (number of "auth" in transaction log)
payment_capture_count : Integer : optional : default=null Optional	The number of payment captures made during the time span of this report on this ledger (number of "capture" in transaction log)
payment_release_count : Integer : optional : default=null Optional	The number of payment releases made during the time span of this report on this ledger (number of "release" in transaction log)
payment_expire_count : Integer : optional : default=null Optional	The number of expired payment requests during the time span of this report on this ledger (number of "expire" in transaction log)
payment_fail_count : Integer : optional : default=null Optional	The number of payment failures during the time span of this report on this ledger (number of "fail" in transaction log)
payment_abort_count : Integer : optional : default=null Optional	The number of payments aborted during the time span of this report on this ledger (number of "abort" in transaction log)
payment_refund_count : Integer : optional : default=null Optional	The number of payment refunds made during the time span of this report on this ledger (number of "refund" in transaction log)
permission_request_count : Integer : optional : default=null Optional	The number of permission requests during the time span of this report on this ledger (number of "pending" in scopes log)
permission_answered_count : Integer : optional : default=null Optional	The number of permissions answered during the time span of this report on this ledger (number of "ok" in scopes log)
permission_fail_count : Integer : optional : default=null Optional	The number of permissions failed during the time span of this report on this ledger (number of "fail" in scopes log)

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¶

mCASH 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, mCASH 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 mCASH.

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: (^|^[a-z]+://([^/:]+.[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: (^|^[a-z]+://([^/:]+.[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[] : SettlementSummary : optional : default=null	Settlement Summary
payout_details[] : PayoutDetail : optional : default=null	Payout Details

Settlement account¶

Look up information about SettlementAccount

GET /settlement_account/<settlement_account_id>/¶

Required auth level: SECRET

Authorized roles: ALL

Retrieve information about a merchant settlement account.

Parameters:	account_id -- The ID of the settlement account.
Status Codes:	200 -- OK 404 -- No account with this ID

Response schema

net_transactions_for[] : String : optional : default=null	This settlement account will receive the net transactions for the merchants listed here
bill_scopes_for[] : String : optional : default=null	This settlement account will pay for value-added services for the merchants listed here

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

ledger : String : optional : default=null Optional	DEPRECATED
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)	The POS this permission request originates from, used for informing user about origin
pos_tid : String : required Data required (new or existing on update)	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, mCASH 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 mCASH

Response schema

ledger : String : optional : default=null Optional	DEPRECATED
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)	The POS this permission request originates from, used for informing user about origin
pos_tid : String : required Data required (new or existing on update)	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, mCASH 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

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 mCASH

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 mCASH
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 : Money : optional : default="0.00"	Permission fee to be deducted from settlement
report_id : String : optional : default=null	The Report that this authorization is included in
report_uri : String : optional : default=null Optional URL	Endpoint for the report that contains the state of the permission request.
ledger_id : String : optional : default=null Optional	DEPRECATED, do not pass
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)	The POS this request originates from, used for informing user about origin
pos_tid : String : required Data required (new or existing on update)	Local transaction id for POS. This must be unique for the POS
rid : String : required Data required (new or existing on update)	mCASH request id
user_info : Json : optional : default=null	User Info

Merchant logo¶

GET /merchant/<merchant_id>/logo¶

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
description : String : optional : default=null	Description

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
description : String : optional : default=null	Description