Combo API for payment claims

​This API is currently in a pilot phase​ and is not yet widely available.

Send payment claims / invoices

1. ​First check which invoicing options are available for the respective customers: 
   
1. Check for an active AvtaleGiro mandate 
2. Check for an eFaktura agreement (refer to the eFaktura documentation at https://www.efaktura.no/developer/documentation 
2. Based on the existence of an active AvtaleGiro mandate and/or eFaktura agreement, you can send a transaction as an AvtaleGiro claim, an eFaktura invoice, or a combination of both. Use the API call: addShipment
   
3. Save the UUIDs used in the addShipment  call so that you can check the status of the shipment and transactions later.

Input fields

The following input fields are used for addShipment.

(Key: C = Compulsory, O = Optional, EO = Either Or, NU = Not used)

​Input	​Input de​​scription	​Input requirements	​eFaktura	​AvtaleGiro	​Combo​
​Audit information	​Information used for auditing and logging messa​​ges. The service replies with the same message identifier sent in.	​	​C	​C	​C
​> Message ID	​A unique identifier for a request/response message pair used for logging.	​String (5-50)	​C	​C	​​C
​Shipment ID	​A unique reference - UUID	​UUID	​C	​C	​C
​Issuer	​Issuer's (creditor) organization number	​String (9)	​C	​NU	​C
​Transactions	​Allows up to a 1000 transactions per shipment.	​Max 1000	​C	​C	​​C
​> Transaction ID	​A unique reference - UUID	​UUID	​C	​C	​C
​> Payment  type	​Specifies the payment type. EFAKTURA: eFaktura Only EFAKTURA_AND_AVTALEGIRO: Combination of both eFaktura and AvtaleGiro EFAKTURA_AND_EXTERNAL_AVTALEGIRO: Combination eFaktura, AvtaleGiro claim sent as BBS-format file AVTALEGIRO: AvtaleGiro only	​EFAKTURA, EFAKTURA_AND_AVTALEGIRO, EFAKTURA_AND_EXTERNAL_AVTALEGIRO, AVTALEGIRO	​C	​C	​​C
​> Document type	​Specifies the eFaktura document type. Only INVOICE can be used in combination with AvtaleGiro. INVOICE: Regular invoice To be supported: CREDIT_NOTE: Credit note. EFAKTURA payment type only. REMINDER: Reminder. EFAKTURA payment type only. COLLECTION_NOTICE: Debt collection notice. EFAKTURA payment type only.	​INVOICE, CREDIT_NOTE, REMINDER, COLLECTION_NOTICE	​C	​NU	​C
​> KID	​Payment reference used for reconciliation and matching AvtaleGiro Transaction with mandate. Mandatory for ATG, optional for eFaktura.	​String (2-25)	​O	​C	​C
​​> Account number	​Creditor's (issuer) account number. Must be a Norwegian account number with 11 digits.	​String (11)	​C	​C	​C
​> Amount	​Due amount to be paid represented as a positive number with two decimals.	​Decimal (>=0,00)	​C	​C	​C
​> Due date	​Date for when the payment is due. eFaktura: Today's date + 3 days up to 12 months AvtaleGiro Today's date + 4 days up to 12 months	​Date	​C	​C	​C
​> eFaktura info	​eFaktura invoice specifications required for Payment types: EFAKTURA, EFAKTURA_AND_AVTALEGIRO, EFAKTURA_AND_EXTERNAL_AVTALEGIRO	​	​C	​NU	​C
​>> eFaktura identifier	​The unique eFaktura address of the receiver (debtor). Use one of "eFaktura identifier", "social security number" or "eFaktura reference"	​Numbers (9)	​EO	​NU	​EO
​​​>> Social security Number	​The receiver's (debtor) social security number. Use one of "eFaktura identifier", "Social security number" or "eFaktura reference"	​Numbers (11)	​EO	​NU	​EO
​>> eFaktura reference	​The eFaktura reference of the receiver unique between issuer (creditor) and receiver (debtor). Use one of "eFaktura identifier", "Social security number" or "eFaktura reference"	​String (0-32)	​EO	​NU	​EO
​> Minimum amount	​Minimum amount to be paid represented as a positive number with two decimals.	​Decimal (>0,00)	​O	​NU	​O
​> Brand name	​Name of the issuer (creditor) that is shown to the eFaktura receiver (debtor).	​String (40)	​C	​NU	​C
​> eFaktura URL	​Link to the human readable format of the eFaktura.	​String (1-255)	​C	​NU	​C
​> Collection Notice Notification	​Receiver's (debtor) contact info for notifications of debt collection notices. Required and only valid for Document type COLLECTION_NOTICE. To be supported.	​	​O	​NU	​O
​>> Email	​A valid email address used for notification of debt collection notices. To be supported.	​String (5-100) (*@*.*)	​EO	​NU	​EO
​>> mobilPhone	​A valid phone number used for notification of debt collection notices. Prefixed with country code (i.e. +4799999999). To be supported.	​String (6\16) (+*)	​EO	​NU	​EO
​> AvtaleGiro info	​AvtaleGiro Claim specifications required for Payment types: AVTALEGIRO, EFAKTURA_AND_AVTALEGIRO	​	​NU	​C	​C
​>> atgNotification	​Specifies if the creditor is notifying the debtor themselves or if bank notification is used. true = Bank notification false = Creditor notification Creditor notification is required for Payment type EFAKTURA_AND_AVTALEGIRO. Both Creditor notification and Bank notification can be used for Payment type AVTALEGIRO​.	​Boolean	​NU	​C	​C
​​>> atgNotification text	​Required for atgNotification = true (Bank notification) Bank notification text for AvtaleGiro sent to debtor from debtor bank. Max length 3360, but should be divided in 80 character lines and maximum 42 lines.	​String (0-3360)	​NU	​O	​O
​>> atgAbbreviated name	​Shortened name of the creditor used by the banks on debtor's account statement and in bank notifications to debtor.	​String (0-10)	​NU	​O	​O
​>> atgExternal reference	​Payment reference for debtor. Displayed by the bank at debtors account statement and bank notification (if chosen). Will override the standard text defined on the AvtaleGiro agreement.	​String (1-25)	​NU	​O	​​O

 

Check shipment status

Using the shipment UUID, make a call to the endpoint getShipmentStatus. The response will include the number of transactions accepted, the number of transactions rejected, and the reasons for any rejections.

An overview of all sent shipments with UUIDs within a time period can be requested by using the getShipment call.

Shipment statuses

IN_PROGRESS - Shipment received and processing. No transaction statuses available.
PROCESSED - Shipment processed and all transactions validated. See transaction level statuses.
STOPPED - Shipment stopped. See transaction level statuses.

Transaction status

It is possible to check the status of individual transactions any time after it has been posted using the API call getTransactionStatus. Combination transactions will have individual statuses for the AvtaleGiro claim and eFaktura invoice, respectively.

AvtaleGiro transaction statuses

IN_PROGRESS – Transaction received and is being processed.
PENDING – Transaction validated and waiting for distribution to debtor/payer bank. The transaction will undergo further processing and validation at the bank. Transactions are sent to banks once per day at approximately 17:00.
PROCESSED – Transaction validated and distributed to debtor/payer bank. The transaction will undergo further processing and validation at the bank. Transactions are sent to banks once per day at approximately 17:00.
REJECTED – The transaction has been rejected by Mastercard Payment Services. The reason will be included in the status message.
NOT_AN_ATG_TRANSACTION – No AvtaleGiro in this transaction.

If a cancellation process has been initiated for an AvtaleGiro transactions the possible statuses are: 

CANCELLATION_IN_PROGRESS - Cancellation received and is being processed.
CANCELLATION_PENDING - Cancellation validated and waiting for bank response.
CANCELLATION_REJECTED - The cancellation has been rejected by Mastercard Payment Services or the payer's bank. The reason will be included in the status message.
CANCELLED - Transaction cancelled by creditor.

eFaktura transaction statuses

IN_PROGRESS – Transaction received and being processed
ACCEPTED – Transaction validated and distributed to debtor/payer
REJECTED – Transaction validated rejected
STOPPED - Transaction stopped by Mastercard Payment Services
CANCELLED – Transaction cancelled by creditor
NOT_AN_EFAKTURA_TRANSACTION – No eFaktura in this transaction

Important to note

If a transaction is sent as a combination of AvtaleGiro and eFaktura and the transaction is rejected by AvtaleGiro, the eFaktura invoice will be parked and not distributed to debtor/payer.

If an AvtaleGiro transaction is sent via this API, any rejected transactions will not appear in lists (e.g. L202, L2603); the status must be found using this API.

Cancel a shipment

To cancel a shipment, use cancelShipment and include the UUID associated with the shipment being cancelled.

Cancel a transaction

To cancel a transaction, use cancelTransaction and include the UUID associated with the transaction being cancelled.​​​​​​​​​

 

Go to topGo back to Developer

​​

​