Search
Payer docsAPI - PlatformAPI - SignUpPayer.eu
HomePayer DocsPayer B2BPayer B2B EventsPayer B2B SignUp
Payer B2B
Introduction
Integration guidelines
Authentication
Authentication
Invoices V2
PUTSends a copy of an invoice.
POSTPays out the outstanding amount from a credit invoice back to the party that made the original payment.
POSTPays an invoice with an outstanding amount from a credit invoice.
POSTCreates a credit invoice with items that credits items from the original invoice, items to be credited are identified by item position.
POSTReturns a credit invoice for given line items.
POSTReturns a credit invoice for the full amount of the provided invoice.
GETReturns an invoice for a given invoice number
GETReturns invoices where the invoice customer have the given reg number or vat id
GETReturns all credit invoices for a given orderId or orderReferenceId
GETReturns invoices with invoice number >= than given invoice number
Invoices V3
Reporting V1
Card Payments
Orders V2
Bank Accounts
Invoice Reminders
Customers V1
Customers V2
Mobile Payments
Cloud Pos V1
Direct Bank Payments
Invoice Aggregations V2
Settlements V2
Payment Requests
Payments V2
Bank Payments V1
Subscriptions

Payer B2B 1

Introduction

The Payer REST API enables you to create magic payment experiences - based on your customers needs. It puts you in the driver's seat with full control of the flow.

Each service has its own set of functions that delivers value individually and can be applied - before, during and after the order moment. This enables you to use the functions to deliver value just in the right micro-moment throughout your customer’s journey.

Even though the services can create value when used individually, combined, you can create magic.

Take command and use single functions or combos in your scenario in the right micro-moment and generate maximum value.

In need of some inspiration or don’t know where to start? Don’t hesitate to contact us for guidance, tips & tricks or examples of experiences to start from

Integration guidelines

Formats

  1. All amounts are in cents, e.g. if you're using USD the amounts will be in cent
  2. ISO-8601 Standard for date and time stamps.
  3. UTF-8 text encoding.

VAT

When specifying prices of items in Orders, the unitPrice and subtotalPrice fields are specified including VAT.

Non-breaking updates of the API

When using Payers API, your service should allow for dynamic changes. Such as:

  1. New valid values for enums may be added.
  2. New fields may be added to a response.

Retrying requests

When sending a non-GET HTTP request to the API, you can add a Payer-Request-ID header with a unique UUID to the request. This header allows you to retry the request (using the same Payer-Request-ID) if you're unsure whether or not Payer successfully handled the request. For example, if there was a network problem so that you couldn't receive the response to the request. If the request has already been handled, a 409 Conflict will be returned. GET requests are excluded from this mechanism, since it's always safe to do GET requests multiple times.

Authentication

Payer B2B uses authentication with a OAuth2 Bearer token for all endpoints except the authentication endpoint. For <credentials>, we use the Base64-encoded string of clientId:clientSecret. On macOS/Linux you can generate it with:

echo -n clientId:clientSecret | base64

On Windows, you can use certutil -encode.

Use the following command with your <credentials> to authenticate:

curl -X POST \
 https://b2b.payer.se/oauth2/token \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <credentials>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=client_credentials

The POST will return a JSON response containing an OAuth2 Bearer token:

{
    "access_token": "some-very-long-token",
    "expires_in": 3599,
    "scope": "",
    "token_type": "bearer"
}

For all other endpoints in Payer B2B, use the access_token from the response as OAuth2 Bearer token with the HTTP header Authorization: Bearer <some-very-long-token>.

The token expires in one hour. You will notice this in the form of a 401 Unauthorized reply to a request. You should act on this reply by performing a re-authentication and then retrying the request. You are also free to keep track of the token age yourself and renew before it expires.

Common authentication errors

If you are not able to access the API, some possible errors are:

  • The access token was not provided in the Authorization header.
  • The Authorization header was not prefixed with Bearer.
  • The access token has expired. Generate a new token and perform the request again.
  • You are not allowed to access the API. Contact Payer if you need access to additional APIs.

If you have other issues with authentication, contact Payer for assistance.

Server
https://b2b.payer.se

Generated server url

Server Variables

Authentication

oauth2 Authentication

FlowClient Credentials
Token URL/oauth2/token
Scopes
NameDescription
No scopes

Sends a copy of an invoice.

Auth
Required Scopes:READWRITE
Request Body
PUT /api/v2/orders/invoices/send
Copy
Responses
200

OK

No response body
400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

503

Service Unavailable

Response
Copy

Pays out the outstanding amount from a credit invoice back to the party that made the original payment.

It is only possible to use credit invoices created with API V2.

Auth
Required Scopes:READWRITE
Request Body
objectobject
invoiceNumberint64
POST /api/v2/orders/invoices/payout-credit
Copy
Responses
200

OK

objectobject
amountint64
bankAccountPayoutobject

If the payout is performed directly to a bank account, this field will be present

maskedAccountNumberstring

The last digits of the account number that the payout is to, to help verification without showing sensitive data

payoutJobIdstring
transactionMessagestring
currencyCodestring

Enum: DKK,EUR,GBP,NOK,SEK,USD,CHF

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

503

Service Unavailable

Response
Copy

Pays an invoice with an outstanding amount from a credit invoice.

It is only possible to use invoices and credit invoices created with API V2.

Auth
Required Scopes:READWRITE
Request Body
objectobject
amountint64

minimum: 1

creditInvoiceNumberint64
toPayInvoiceAggregationIdstring

The Monthly Invoice Statement that should be paid. One of toPayInvoiceNumber and toPayInvoiceAggregationId is required.

toPayInvoiceNumberint64

The Invoice that should be paid. One of toPayInvoiceNumber and toPayInvoiceAggregationId is required.

POST /api/v2/orders/invoices/pay-with-credit
Copy
Responses
200

OK

No response body
400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

503

Service Unavailable

Response
Copy

Creates a credit invoice with items that credits items from the original invoice, items to be credited are identified by item position.

An Invoice created with the V2 API can only be credited using the V2 API A credit invoice can be linked to the original invoice or it can be standalone. When using the standalone credit invoice as payment for another invoice, the original invoice will not be affected - no debt will be added to the original invoice. Either invoiceNumber or referenceId must be provided

Auth
Required Scopes:READWRITE
Request Body
objectobject
externalInvoiceNumberstring

Optional external invoiceNumber when this credit invoice is a mirror of credit invoice in an external system. Must be unique.

maxLength: 36

minLength: 0

invoiceDatedate

Invoice date can not be in the future. If not specified, defaults to today.

invoiceNumberint64

Required if no referenceId is provided.

itemsarray[object]

Positions and quantities to be credited from the original invoice

positionint32
quantitynumber

minimum: 0

referenceIdstring

Required if no invoiceNumber is provided.

maxLength: 64

minLength: 0

standaloneboolean

true means that this credit invoice will be a standalone credit invoice with no link to the original invoice.

POST /api/v2/orders/invoices/credit/partial
Copy
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

503

Service Unavailable

Response
Copy

Returns a credit invoice for given line items.

An Invoice created with the V2 API can only be credited using the V2 API A credit invoice can be linked to the original invoice or it can be standalone. When using the standalone credit invoice as payment for another invoice, the original invoice will not be affected - no debt will be added to the original invoice. Either invoiceNumber or referenceId must be provided

Auth
Required Scopes:READWRITE
Request Body
POST /api/v2/orders/invoices/credit/manual
Copy
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

503

Service Unavailable

Response
Copy

Returns a credit invoice for the full amount of the provided invoice.

An Invoice created with the V2 API can only be credited using the V2 API A credit invoice can be linked to the original invoice or it can be standalone. When using the standalone credit invoice as payment for another invoice, the original invoice will not be affected - no debt will be added to the original invoice. Either invoiceNumber or referenceId must be provided

Auth
Required Scopes:READWRITE
Request Body
objectobject
deliveryTypestring

Optional delivery type. If not specified, the delivery type of the referenced invoice will be used

Enum: NONE,EMAIL,PRINT,EINVOICE,SMS

externalInvoiceNumberstring

Optional external invoiceNumber when this invoice is a mirror of an invoice in an external system. Must be unique.

maxLength: 36

minLength: 0

invoiceDatedate

Invoice date can not be in the future. If not specified, defaults to today.

invoiceNumberint64

Required if no referenceId is provided.

referenceIdstring

Required if no invoiceNumber is provided.

maxLength: 64

minLength: 0

standaloneboolean

true means that this credit invoice will be a standalone credit invoice with no link to the original invoice.

POST /api/v2/orders/invoices/credit/full
Copy
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

503

Service Unavailable

Response
Copy

Returns an invoice for a given invoice number

Note: By default, the invoice is returned in Inc-Vat format, even if the invoice was originally created with a different calculation mode. Please use the originalCalculationModeResponse flag if you don't want that. Also note: An Invoice created with the V2 API can only be fetched using the V2 API.

Auth
Required Scopes:READWRITE
Query String
invoiceNumberinteger
referenceIdstring

maxLength: 64

minLength: 0

externalInvoiceNumberstring
originalCalculationModeResponseboolean

The Items in the response are normally returned in the Inc-Vat format, even if the invoice was originally created with a different calculation mode. This flag makes it possible to get the Items in their original calculation mode in the response. If you enable this it's suggested that you use a deserializer that supports polymorphic deserialization and let the it use the Item 'calculationMode' attribute to decide which sub model to use.

GET /api/v2/orders/invoices
Copy
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

503

Service Unavailable

Response
Copy

Returns invoices where the invoice customer have the given reg number or vat id

Batch size is 20. If more invoices exists, the next invoice number is returned to be used in future requests. Note: By default, the invoice is returned in Inc-Vat format, even if the invoice was originally created with a different calculation mode. Please use the originalCalculationModeResponse flag if you don't want that. Also note: An Invoice created with the V2 API can only be fetched using the V2 API.

Auth
Required Scopes:READWRITE
Query String
regNumberstring
customerVatIdstring
fromInvoiceNumberinteger
originalCalculationModeResponseboolean

The Items in the response are normally returned in the Inc-Vat format, even if the invoice was originally created with a different calculation mode. This flag makes it possible to get the Items in their original calculation mode in the response. If you enable this it's suggested that you use a deserializer that supports polymorphic deserialization and let the it use the Item 'calculationMode' attribute to decide which sub model to use.

GET /api/v2/orders/invoices/reg-number
Copy
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

503

Service Unavailable

Response
Copy

Returns all credit invoices for a given orderId or orderReferenceId

An Invoice created with the V2 API can only be fetched using the V2 API

Auth
Required Scopes:READWRITE
Query String
orderIdinteger
orderReferenceIdstring

maxLength: 48

minLength: 0

GET /api/v2/orders/invoices/credit
Copy
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

503

Service Unavailable

Response
Copy

Returns invoices with invoice number >= than given invoice number

Batch size is 20. If more invoices exists, the next invoice number is returned to be used in future requests. Note: By default, the invoice is returned in Inc-Vat format, even if the invoice was originally created with a different calculation mode. Please use the originalCalculationModeResponse flag if you don't want that. Also note: An Invoice created with the V2 API can only be fetched using the V2 API.

Auth
Required Scopes:READWRITE
Query String
fromInvoiceNumberinteger
originalCalculationModeResponseboolean

The Items in the response are normally returned in the Inc-Vat format, even if the invoice was originally created with a different calculation mode. This flag makes it possible to get the Items in their original calculation mode in the response. If you enable this it's suggested that you use a deserializer that supports polymorphic deserialization and let the it use the Item 'calculationMode' attribute to decide which sub model to use.

GET /api/v2/orders/invoices/batch
Copy
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

503

Service Unavailable

Response
Copy
Powered By