Merchant API Reference

This is the reference documentation for the Merchant API. The Merchant API enables merchants to interact with mCASH, 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 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: (^|^w+://([^/:]+|([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+://([^/:]+|([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
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: (^|^w+://([^/:]+|([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+://([^/:]+|([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:

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

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: (^|^w+://([^/:]+.[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: (^|^w+://([^/:]+.[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+://([^/:]+.[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

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