MobilePay Invoice

Developer Documentation

Web API Reference

InvoiceDirect

High level InvoiceDirect flow diagram

Create InvoiceDirect

You can create an invoice directly to MobilePay app. Notice that request require a customer mobile phone number. Check how invoice looks in the app here.

POST api/v1/merchants/{merchantId}/invoices
Input
Parameter Sub Parameter Type Description
InvoiceIssuer   guid Required. The ID of the invoicing department/branch of the merchant.
ConsumerAlias   object Required. Mobile alias of the MobilePay user to be invoiced.
  Alias string Required. Mobile phone number of the MobilePay user. Should start with a ‘+’ sign and country phone code.
E.g. +4512345678 or +35812345678
  AliasType string Required. Alias type of the MobilePay user.
Only value allowed is Phone.
ConsumerName   string Full name of the MobilePay user.
TotalAmount   decimal Required. The requested amount to be paid.
>0.00, decimals separated with a dot.
TotalVatAmount   decimal VAT amount. Decimals separated with a dot.
ConsumerAddressLines           string[]     Address of consumer receiving the invoice.
DeliveryAddressLines           string[]     Delivery address.
InvoiceNumber                 string     At least one of the fields InvoiceNumber or PaymentReference is required. Invoice number. It will be used if PaymentReference is not filled.
IssueDate                     date       Issue date of invoice. ISO date format: YYYY-MM-DD
DueDate                       date       Required. Payment due date. Must be between today and 400 days ahead, otherwise the request will be declined. ISO date format: YYYY-MM-DD
OrderDate   date Order date of invoice. ISO date format: YYYY-MM-DD
DeliveryDate   date Delivery date of invoice. ISO date format: YYYY-MM-DD
Comment   string Additional information to the consumer.
MerchantContactName             string     Contact name for the individual who issued the invoice.
MerchantOrderNumber             string     The merchant order number for the invoice used internally by the merchant.
BuyerOrderNumber             string     The buyer order number for the invoice used externally by the merchant.
PaymentReference             string(60)* At least one of the fields InvoiceNumber or PaymentReference is required. Reference used on the payment to do reconciliation if merchant has chosen Instant Transfer method. If not filled, InvoiceNumber will be used as reference.
InvoiceUrl             string URL to the Invoice PDF provided by merchant.
InvoiceArticles   array At least one is required.
  ArticleNumber string Article Number, e.g. 123456ABC
  ArticleDescription string Required. Article Description.
  VATRate decimal VAT Rate of article.
  TotalVATAmount decimal Total VAT amount of article. Decimals separated with a dot.
  TotalPriceIncludingVat decimal Total price of article including VAT.
  Unit string Unit, e.g. Pcs, Coli.
  Quantity decimal Quantity of article. Allowed to have more than two decimal digits.
  PricePerUnit             decimal Price per unit. Allowed to have more than two decimal digits.
  PriceReduction decimal Price reduction.
  PriceDiscount decimal Price discount.
  Bonus decimal Bonus of article.
Note:

* Even though "PaymentReference" can contain up to 60 symbols the recommendation is to use up to 30 symbols. For instant transfers "PaymentReference" will be truncated up down to 30 symbols and included in bank statement.

Example
{
  "InvoiceIssuer": "efd08c19-24cf-4833-a4a4-bfa7bd58fbb2",
  "ConsumerAlias": {
    "Alias": "+4577007700",
    "AliasType": "Phone"
  },
  "ConsumerName": "Consumer Name",
  "TotalAmount": 360,
  "TotalVATAmount": 72,
  "ConsumerAddressLines": [
    "Paradisæblevej 13",
    "CC-1234 Andeby", 
    "WONDERLAND"
  ],
  "DeliveryAddressLines": [
    "Østerbrogade 120",
    "CC-1234 Andeby",
    "WONDERLAND"
  ],
  "InvoiceNumber": "301",
  "IssueDate": "2018-02-12",
  "DueDate": "2018-03-12",
  "OrderDate": "2018-02-05",
  "DeliveryDate": "2018-02-10",
  "Comment": "Any comment",
  "MerchantContactName": "Snowboard gear shop",
  "MerchantOrderNumber": "938",
  "BuyerOrderNumber": "631",
  "PaymentReference": "186",
  "InvoiceArticles": [
    {
      "ArticleNumber": "1-123",
  "ArticleDescription": "Process Flying V Snowboard",
      "VATRate": 25,
      "TotalVATAmount": 72,
      "TotalPriceIncludingVat": 360,
      "Unit": "1",
      "Quantity": 1,
      "PricePerUnit": 288,
      "PriceReduction": 0,
      "PriceDiscount": 0,
      "Bonus": 5
    }      
  ]
}

Response

HTTP 202 Accepted
{
    "InvoiceId" : "63679ab7-cc49-4f75-80a7-86217fc105ea"
}
Note: If not accepted, invoice will expire 30 days after due date.

Create multiple invoices

POST api/v1/merchants/{merchantId}/invoices/batch

You can create up to 2000 invoices per single batch.

Input (an array of objects used to create single invoice)
[
  {
     // InvoiceDirect input
  },
  {
     // InvoiceDirect input
  },
  ...
]
Response
HTTP 202 Accepted
{
  "Accepted": [
    {
      "InvoiceNumber": "<original invoice number sent by the merchant>",
      "InvoiceId": "66119129-aaf7-4ad0-a5b1-62382932b5c6"
    },
    {
      "InvoiceNumber": "<original invoice number sent by the merchant>",
      "InvoiceId": "5e3030a3-61ff-4143-a6bd-8457a09bcb0d"
    },
    ...
  ],
  "Rejected": [
    {
      "InvoiceNumber": "<original invoice number sent by the merchant>",
           "Errors:[
              {
              "ErrorText": "<description of error>",
              "ErrorCode": 10504
              }
       ]
    },
    ...
  ]
}
Note: When multiple invoices are sent, most of the validation is applied asynchronously. The result are sent via callbacks.

High level InvoiceLink flow diagram

You can create an invoice and receive a link. That link can be sent to the user by any channel like email, sms, etc. and user can choose to pay with MobilePay. Check InvoiceLink flows and how invoice looks in the app here.

Note:

* Request does not require a ConsumerAlias. It's because InvoiceLink can be paid by any MobilePay user.

* InvoiceLink has an optional "RedirectUrl" property. It can be set when creating single or multiple Invoice links. User will be redirected to provided url after accepting invoice link payment for the future, or paying for it instantly. Redirect will happen with appropriate query parameters, i.e. if provided RedirectUrl value is "https://ProvidedUrl.com/" in case of accepted payment user will be redirected to "https://ProvidedUrl.com/?status=accepted" and in case of instant payment user will be redirected to "https://ProvidedUrl.com/?status=paid". This feature supports both webUrls and deeplinks.

POST api/v1/merchants/{merchantId}/invoices/link
Input
Parameter Sub Parameter Type Description
InvoiceIssuer   guid Required. The ID of the invoicing department/branch of the merchant.
ConsumerAlias   object Mobile alias of the MobilePay user to be invoiced.
  Alias string Mobile phone number of the MobilePay user. Should start with a ‘+’ sign and country phone code.
E.g. +4512345678 or +35812345678
  AliasType string Alias type of the MobilePay user. This will be autofilled in the landing page if user opens the link not on the phone
Only value allowed is Phone.
ConsumerName   string Full name of the MobilePay user.
TotalAmount   decimal Required. The requested amount to be paid.
>0.00, decimals separated with a dot.
TotalVatAmount   decimal VAT amount. Decimals separated with a dot.
ConsumerAddressLines           string[]     Address of consumer receiving the invoice.
DeliveryAddressLines           string[]     Delivery address.
InvoiceNumber                 string     At least one of the fields InvoiceNumber or PaymentReference is required. Invoice number.
IssueDate                     date       Issue date of invoice. ISO date format: YYYY-MM-DD
DueDate                       date       Required. Payment due date. Must be between today and 400 days ahead, otherwise the request will be declined. ISO date format: YYYY-MM-DD
OrderDate   date Order date of invoice. ISO date format: YYYY-MM-DD
DeliveryDate   date Delivery date of invoice. ISO date format: YYYY-MM-DD
Comment   string Additional information to the consumer.
MerchantContactName             string     Contact name for the individual who issued the invoice.
MerchantOrderNumber             string     The merchant order number for the invoice used internally by the merchant.
BuyerOrderNumber             string     The buyer order number for the invoice used externally by the merchant.
PaymentReference             string(60)* At least one of the fields InvoiceNumber or PaymentReference is required. Reference used on the payment to do reconciliation. If not filled, invoice number will be used as reference.
InvoiceUrl             string URL to the Invoice PDF provided by merchant.
RedirectUrl             string Redirect url for accepting and paying invoice link.
InvoiceArticles   array At least one is required.
  ArticleNumber string Article Number, e.g. 123456ABC
  ArticleDescription string Required. Article Description.
  VATRate decimal VAT Rate of article.
  TotalVATAmount decimal Total VAT amount of article. Decimals separated with a dot.
  TotalPriceIncludingVat decimal Total price of article including VAT.
  Unit string Unit, e.g. Pcs, Coli.
  Quantity decimal Quantity of article. Allowed to have more than two decimal digits.
  PricePerUnit             decimal Price per unit. Allowed to have more than two decimal digits.
  PriceReduction decimal Price reduction.
  PriceDiscount decimal Price discount.
  Bonus decimal Bonus of article.
Note:

* Even though "PaymentReference" can contain up to 60 symbols the recommendation is to use up to 30 symbols. For instant transfers "PaymentReference" will be truncated up down to 30 symbols and included in bank statement.

Example
{
  "InvoiceIssuer": "efd08c19-24cf-4833-a4a4-bfa7bd58fbb2",
  "ConsumerAlias": {
    "Alias": "+4577007700",
    "AliasType": "Phone"
  },
  "ConsumerName": "Consumer Name",
  "TotalAmount": 360,
  "TotalVATAmount": 72,
  "ConsumerAddressLines": [
    "Paradisæblevej 13",
    "CC-1234 Andeby", 
    "WONDERLAND"
  ],
  "DeliveryAddressLines": [
    "Østerbrogade 120",
    "CC-1234 Andeby",
    "WONDERLAND"
  ],
  "InvoiceNumber": "301",
  "IssueDate": "2018-02-12",
  "DueDate": "2018-03-12",
  "OrderDate": "2018-02-05",
  "DeliveryDate": "2018-02-10",
  "Comment": "Any comment",
  "MerchantContactName": "Snowboard gear shop",
  "MerchantOrderNumber": "938",
  "BuyerOrderNumber": "631",
  "PaymentReference": "186",
  "RedirectUrl" : "https://ProvidedUrl.com/"
  "InvoiceArticles": [
    {
      "ArticleNumber": "1-123",
      "ArticleDescription": "Process Flying V Snowboard",
      "VATRate": 25,
      "TotalVATAmount": 72,
      "TotalPriceIncludingVat": 360,
      "Unit": "1",
      "Quantity": 1,
      "PricePerUnit": 288,
      "PriceReduction": 0,
      "PriceDiscount": 0,
      "Bonus": 5
    }      
  ]
}
Response
HTTP 202 Accepted
{
    "InvoiceId": "c5d4fde3-81e2-49de-8cfe-8c96f449e367",
    "Links": [
        {
            "Rel": "user-redirect",
            "Href":"https://api.sandbox.mobilepay.dk/invoice-restapi/api/v1/consumers/me/invoices/invoices/c5d4fde3-81e2-49de-8cfe-8c96f449e367/link"
        }
    ]
}
Note:

If not accepted, invoice link will expire 30 days after due date. After expiration invoice link data and PDF will be deleted.

POST api/v1/merchants/{merchantId}/invoices/link/batch

You can create up to 2000 invoice links per single batch.

[
  {
    InvoiceLink input,
  },
  {
    InvoiceLink input,
  },
  ...
]
Response
HTTP 202 Accepted
{
  "Accepted": [
    {
      "InvoiceNumber": "<original invoice number sent by the merchant>",
      "InvoiceId": "66119129-aaf7-4ad0-a5b1-62382932b5c6"
    },
    {
      "InvoiceNumber": "<original invoice number sent by the merchant>",
      "InvoiceId": "5e3030a3-61ff-4143-a6bd-8457a09bcb0d"
    },
    ...
  ],
  "Rejected": [
    {
      "InvoiceNumber": "<original invoice number sent by the merchant>",
           "Errors:[
              {
              "ErrorText": "<description of error>",
              "ErrorCode": 10504
              }
       ]
    },
    ...
  ]
}
Note: The success response is not much different from the regular, non-batch response, but it doesn't contain the link itself. This is because we are processing batches asynchronously and can't return an immediate result. The InvoiceLink URLs will be sent back to you via a callback, as soon as they're created.

Cancel invoice

You can cancel an invoice which has not yet been paid, rejected and has not expired. If the user has chosen to pay at a later point, then the invoice can still be canceled by the merchant. The customer does not receive a notification. Changes will be visible in the MobilePay Activity List. The pending Invoice Payment will be changed to canceled. On payment date (if the user set the invoice to be paid at later point), MobilePay checks the status of the invoice. If it is canceled , then MobilePay ignores “Pay” command.

PUT api/v1/merchants/{merchantId}/invoices/{invoiceId}/cancel
Response
HTTP 204 No Content

Get invoice details

GET api/v1/merchants/{merchantId}/invoices/{invoiceId}
Response
HTTP 200 OK
{
    "InvoiceId": "578a9f10-4e81-4265-bbae-2e8fa33cb83b",
    "InvoiceNumber": "301",
    "IssueDate": "2018-07-02",
    "DueDate": "2018-08-02",
    "PaymentDate": "2018-08-23",
    "Comment": "Sample Invoice",
    "InvoiceArticles": [
        {
          "ArticleNumber": "1-123",
          "ArticleDescription": "Process Flying V Snowboard",
          "TotalPriceIncludingVat": 360,
          "Quantity": 1,
          "PricePerUnit": 288
        }
    ],
    "CurrencyCode": "DKK",
    "TotalAmount": 360,
    "InvoiceVatTotals": [
        {
            "VatRate": 25,
            "TotalVatAmount": 72
        }
    ],
    "TotalVatAmount": 72,
    "TotalAmountExcludingVat": 288,
    "MerchantId": "f3dd9011-d930-4063-901d-2a47621e5b76",
    "InvoiceIssuerId": "238fe387-f4a4-40e7-ae8a-4c107da2c0ad",
    "InvoiceIssuerName": "Invoice Issuer 1",
    "InvoiceIssuerAddress": "Edwin Rahrs Vej 2-12",
    "InvoiceIssuerZipcode": "8220",
    "InvoiceIssuerCity": "Brabrand",
    "MerchantIsoCountryCode": "DK",
    "LogoUrl": "https://api.qa.mobilepay.dk/invoice-restapi/api/v1/invoiceissuers/238fe387-f4a4-40e7-ae8a-4c107da2c0ad/logo",
    "Status": "created",
    "InvoiceUrl":"https://api.merchant.dk/invoice/578a9f10-4e81-4265-bbae-2e8fa33cb83b/pdf",
    "PaymentTransactionId": "d1da2195-01c1-4981-bdde-04eb82e362ab",
    "PaymentReference": "ABC-123"
}

Get invoice status

GET api/v1/merchants/{merchantId}/invoices/{invoiceId}/status
Response
HTTP 200 OK
{
    "InvoiceId" : "5e1210f9-4153-4fc3-83ec-2a8fc4843ea6",
    "Status" : "created"
}

The table below shows all possible statuses.

Status Explanation Type
created Merchant created the Invoice Intermediate
invalid Invoice validation failed Intermediate
accepted User swiped to accept the Invoice Intermediate
paid Invoice was paid Final
rejected User rejected the Invoice Final
expired User did not do do anything until Invoice DueDate + 30 days Final
canceled You canceled this invoice. Final

User accepts the invoice and then pays it immediately or schedules a future payment. The user can change the date, for when the invoice should be paid in the MobilePay app, but nor more than 30 days from the DueDate. For InvoiceLink to be in rejected state, the user needs to have first accepted the invoice and scheduled for a future payment. Afterwards, it is possible for the user to reject the invoice.

An expired status can happen, if the user schedules payment for the future, then MobilePay tries to execute it, but an error happens (for example: card is expired) and the user does not change it and just ignores the payment. In the end that payment will expire.

There are two validation steps :

  1. Merchant validation: If all is good, then MobilePay create the invoice, send the callback created to the merchant, and push message to the user. The outcome of this validation is that the Invoice is created and delivered to the user, or the Invoice failed to be created, and is returned to the merchant. If the validation fails, then MobilePay does not create invoice as an entity in MobilePay domain, so in a way it is kinda a final state.

  2. User validation: Card validation, user status.. etc. The invoice is delivered to the user, when the merchant received callback about created invoice. The outcome of this validation is either that the Invoice is paid or an error message is returned in the app.

The first state is either created or invalid. If you received a callback with status created then the Invoice has been delivered to the user.

Invoice status flow can be visualized by the following diagram.

Goal of this functionality is for Invoice Issuer to ask users phone number and consent to receive Invoices directly to MobilePay (InvoiceDirect).

You can request for consent to send InvoiceDirect to a payer with particular invoice. Consent window is displayed to the user after InvoiceLink is paid. If user has already granted consent to the invoice issuer, consent window will not be displayed to the user.

POST api/v1/directinvoiceconsents
Input
Parameter Type Description
InvoiceId guid Required. The ID of the invoice to which consent request will be attached.
Example
{
  "invoiceId": "c0b6e35d-9dfb-47d4-9c9c-1cdfd181e0a4"
}
Response
HTTP 201 Created
{
  "ConsentId": "e518e841-c058-422c-b8d9-d4d71bf671c4",
  "InvoiceId": "c0b6e35d-9dfb-47d4-9c9c-1cdfd181e0a4",
  "PhoneNumber": null,
  "State": "Pending"
}

Get all consents in specified state

You will get full list of users who granted consent for specific invoice issuer. Users phone number will be provided too.

GET /api/v1/directinvoiceconsents
Input (query string parameters)
Parameter Type Description
InvoiceIssuerId string(guid) Required. The ID of the invoicing department/branch of the merchant.
State string Required. State of consents to return.
PagingState string Optional.

The table below shows all possible consent statuses.

Status Explanation Type
pending User has not made an action regarding this consent Intermediate
granted User has granted direct invoice consent Final
denied User has denied direct invoice consent Final
Example
GET /api/v1/directinvoiceconsents?invoiceIssuerId=6bb6aff1-b88b-455a-a0ad-c4d1fec2e5d7&state=granted
Response
HTTP 200 OK
{
  "GrantedConsents": [
    {
      "ConsentId": "e518e841-c058-422c-b8d9-d4d71bf671c4",
      "InvoiceId": "c0b6e35d-9dfb-47d4-9c9c-1cdfd181e0a4",
      "PhoneNumber": "+4577007700",
      "State": "Granted",
      "GrantedOn": "2021-01-01T12:34:56+00:00"
    }
  ],
  "PagingState": null
}
Note: Endpoint supports only granted status.

You can check state of your specific request - if user granted/denied consent with that request or maybe request is still pending.

GET /api/v1/directinvoiceconsents/{consentId}
Example
GET /api/v1/directinvoiceconsents/e518e841-c058-422c-b8d9-d4d71bf671c4
Response
HTTP 200 OK
{
  "ConsentId": "e518e841-c058-422c-b8d9-d4d71bf671c4",
  "InvoiceId": "c0b6e35d-9dfb-47d4-9c9c-1cdfd181e0a4",
  "PhoneNumber": "+4577007700",
  "State": "Pending",
  "GrantedOn": null
}

DirectInvoiceConsent flow in application

Error Codes

All of the endpoints described above can return an error response of this structure:

Name Type Description
correlation_id guid Unique id used for logging and debugging purposes.
error string Error type. Possible values: DomainError, InputError & ServerError.
error_code string Unique error code.
error_description string Human-friendly error description.
error_context string Identifies context in which error has occured.
  1. HTTP 400 , if request input is invalid
      {
       "correlation_id": "54ccc98b-7d9f-40ea-8c1a-249d57126c39",
       "error": "InputError",
       "error_code": null,
       "error_description": "input.TotalAmount : Invalid input\r\n",
       "error_context": "Invoices"
      }
    
  2. HTTP 409 , request is not compatible with a current state
      {
       "correlation_id": "8c153279-98f1-4e33-b053-3c6e3555adff",
       "error": "DomainError",
       "error_code": "10504",
       "error_description": "Invoice has already been paid",
       "error_context": "Invoices"
      }
    
  3. HTTP 500 , server error
      {
       "correlation_id": "56db684c-7845-4abf-9f19-5632a625a47b",
       "error": "ServerError",
       "error_code": null,
       "error_description": "The given key was not present in the dictionary.",
       "error_context": "Invoices"
      }
    

When creating InvoiceDirect or InvoiceLink these values can be returned as error_code and error_description:

Error Code Error Description
10101 MobilePay user not found
10102 MobilePay user not available
10103 MobilePay user not found
10104 Invoice already exists
10105 Technical error - please contact MobilePay developer support developer@mobilepay.dk
10008 Total amount must be greater than 0
10201 Total invoice amount is exceeded
10202 Invoice issuer not found
10203 Account validation error
10204 Account validation error
10205 Technical error - please contact MobilePay developer support developer@mobilepay.dk
10301 Invoice already exists
10302 Merchant not found
10303 Invoice issuer not found
10304 MobilePay user not found
10305 MobilePay user not found
10306 MobilePay user not found
10310 DueDate must be no later than 400 days from today
10311 DueDate must be today or later
10312 IssueDate must be no later than today
10314 Your daily limit has been reached. No more than 10 invoices can be created per consumer per merchant per day.

Validations

A set of business rules apply for an invoice before it gets created. If any of following rules fail, an invoice falls to Not Created state and a response with error_code and error_description is returned.

Field Country Validation Error Code Description
DueDate DK/FI CreatedDate <= DueDate < CreatedDate + 400 days 10310/10311 DueDate must be no more than 400 days in the future.
IssueDate DK/FI IssueDate <= CreatedDate 10312 IssueDate can not be later than invoice creation date.
TotalAmount DK TotalAmount <= 15000 DKK 10201 TotalAmount is limited to 15000 DKK.
  FI TotalAmount <= 2000 EUR 10201 TotalAmount is limited to 2000 EUR.

If all of the fields in the request are exactly the same as some existing invoice’s fields, the duplication validation fails and the invoice cannot be created.

Limits