Skip to main content

Invoice

Payment attachments V2

The purpose of payment attachments V2 is to replace existing invoice PDF functionality and to offer more flexibility for the merchant. With this new functionality you will be able to choose how attachment will be presented to the user:

  • External URL. Your own link to the payment document.
  • Attachment details. Extra payment details.
  • MobilePay generated PDF. PDF document generated from the attachment details.

Subscriptions attachment

The old way how we create invoice PDF attachments remains, but will be deprecated by the end of 2021.

Create & Update

Payment attachments on top of the payment can be created with a separate request:

`PUT /api/providers/{providerId}/payments/{paymentId}/attachment`

{
"external_attachment_url" : "https://example.com/link/to/e_g_invoice/12345/pdf",
"generate_pdf" : false,
"attachment_details" : {
"document_title": "Company's Faktura",
"hide_payment_point_address": false,
"consumer_name": "John Johnson",
"consumer_phone_number": "+4544667788",
"total_amount": 10,
"total_vat_amount": 10,
"total_amount_ex_vat": 9,
"issue_date": "2018-08-22",
"invoice_number": "58652",
"order_date": "2018-08-22",
"due_date": "2018-08-22",
"consumer_address_lines": [
"Paradisæblevej 13",
"CC-1234 Andeby",
"Wonderland"
],
"articles": [
{
"article_number": "456",
"article_description": "Lorem ipsum dolor sit amet",
"vat_rate": 25,
"total_vat_amount": 25,
"total_price_including_vat": 25,
"unit": "pcs",
"quantity": 6,
"price_per_unit": 60
}
],
"price_reduction": 1.2,
"price_discount": 2,
"bonus": 5,
"merchant_contact_name": "Some Company",
"delivery_address_lines": [
"Østerbrogade 120",
"CC-1234 Andeb"
],
"payment_reference": "ABCD1234",
"delivery_date": "2018-08-22",
"merchant_order_number": "ABCD1234",
"buyer_order_number": "ABCD1234",
"comment": "Lorem ipsum dolor sit amet, eros faucibus aliqua erat aliquam odio vitae."
}
}

You are able to provide your own URL link to payment document by passing it as external_attachment_url value. If you want MobilePay to generate PDF for you, you simply set generate_pdf to true in the request and fill attachment_datails with values which will be used to generate the PDF file. You can also provide attachment_details without generating PDF file, details will be visible in MobilePay payment receipt and confirmation screens.

generate_pdf cannot be set to true when external_attachment_url is provided.

Every subsequent request will overwrite the previous one.

We reduced the amount of mandatory fields in attachment_datails:

ParameterSub ParameterTypeDescriptionRequirement
document_titlestring(60)Used as document title in PDF document.Optional
hide_payment_point_addressbooleanHides payment point address. Default is false.Optional
consumer_namestringFull name of the user.Optional
consumer_phone_numberstringMobile phone number of MobilePay user.Optional
total_amountdecimalThe requested amount to be paid.Required
total_vat_amountdecimalTotal VAT amount.Optional
total_amount_ex_vatdecimalTotal amount excluding VAT.Optional
issue_datedateIssue date of the document.Optional
invoice_numberstringInvoice number for invoice documents.Optional
order_datedateOrder date.Optional
due_datedatePayment due date.Optional
consumer_address_linesstring[]Address of consumer receiving the document.Optional
articlesarrayAt least one array element is required.Required
article_numberstringArticle number, e.g.: 123456ABC.Optional
article_descriptionstringArticle description.Required
vat_ratedecimalVAT rate of an article.Optional
total_vat_amountdecimalTotal VAT amount of an article.Optional
total_price_including_vatdecimalTotal price of an article including VAT. Can be negative.Optional
unitstringUnit, e.g.: pcs, coli, kg, m.Optional
quantitydecimalQuantity of an article.Optional
price_per_unitdecimalPrice per unit.Optional
price_reductiondecimalPrice reduction.Optional
price_discountdecimalPrice discount.Optional
bonusdecimalBonus.Optional
merchant_contact_namestringContact name of the individual who issued the document.Optional
delivery_address_linesstring[]Delivery address.Optional
payment_referencestring(60)Any extra reference to be presented in the generated PDF file.Optional
delivery_datedateDelivery date of the document.Optional
merchant_order_numberstringThe merchant order number for the document used internally by the merchant.Optional
buyer_order_numberstringThe buyer order number for the document used internally by the merchant.Optional
commentstringAdditional information for the consumer. "\n" can be used for a line break, e.g.: "First line. \nSecond line."Optional

Review & Delete

GET /api/providers/{providerId}/payments/{paymentId}/attachment to get the details of the payment attachment.

GET /api/providers/{providerId}/payments/{paymentId}/attachment/pdf to download PDF attachment(if it was created).

DELETE /api/providers/{providerId}/payments/{paymentId}/attachment to delete payment attachment.

PDF invoice examples

This is the example of how your data will look like to user in the MobilePay, when it is generated to PDF file.

PDF

Marking from an exampleMapping SubscriptionsENDKFI
1document_titleN/AN/AN/A
2Subscription provider logoN/AN/AN/A
3Subscription provider nameN/AN/AN/A
4Subscription provider addressN/AN/AN/A
5Merchant CVRCompany IDCVRY-tunnus
6merchant_contact_nameN/AN/AN/A
7consumer_nameN/AN/AN/A
8consumer_address_linesN/AN/AN/A
9consumer_phone_numberN/AN/AN/A
10delivery_address_linesDelivery addressLeveringsadresseToimitusosoite
11delivery_dateDelivery dateLeveringsdatoToimituspäivä
12buyer_order_numberBuyers order IDKøbers ordrenummerOstajan tilausnumero
13merchant_order_numberMerchant order IDSælgers ordrenummmerMyyjän tilausnumero
14order_dateOrder dateOrdredatoPäivä
15invoice_numberInvoice numberFakturanummerLaskun numero
16issue_dateIssue dateFakturadatoLaskun päivä
17due_dateDue dateBetalingsdatoEräpäivä
18payment_referencePayment referenceBetalingsreferenceMaksun viite
19article_numberItem IDVarenummerTuotenumero
20article_descriptionDescriptionBeskrivelseKuvaus
21quantityQuantityAntalMäärä
22unitTypeEnhedYksikkö
23price_per_unitQuantity priceEnhedsprisYksikköhinta
24vat_rateVATMomsALV
25total_price_including_vatTotalTotalYhteensä
26price_reductionPrice reductionTotal prisnedsættelseKokonaishinta
27price_discountDiscountTotal rabatAlennus
28bonusBonusTotal bonusKokonaisbonus
29total_amount_ex_vatTotal ex VATTotal uden momsYhteensä ilman ALV
30total_vat_amountTotal VATMomsALV yhteensä
31total_amountTotalTotalYhteensä
32commentCommentsKommentarKommentit

App screens

Payment attachments are represented in payment/one-off confirmation and receipt screens.

MobilePay generated PDF + Attachment detailsAttachment details
PDF attachmentAttachment details
External URL + Attachment detailsExternal URL
PDF attachmentAttachment details