Invoice Payments

Payment Resource

The payment resource and all general sub-resources can be found in the core payment resources section.

Legal Address

The legaladdress resource lists the legal address of a consumer for a specific payment. It is retrieved from the population register, either from SPAR (Sweden) or DSF (Norway).

Request
GET /psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/legaladdress/ HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "legalAddress": {
       "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/legaladdress",
       "addressee": "firstname and lastname",
       "coAddress": "coAddress",
       "streetAddress": "streetAddress",
       "zipCode": "zipCode",
       "city": "city",
       "countryCode": "countryCode"
    }
}

Properties

PropertyData typeDescription
paymentstringThe URI to the payment the resource belong to.
legalAddress.idstringThe URI of the current legaladdress resource.
legalAddress.addresseestringThe firstname and lastname of the person that receives the invoice.
legalAddress.coAddressstringThe C/o address. Only used if applicable.
legalAddress.streetAddressstringThe street address of the person that receives the invoice.
legalAddress.zipCodestringThe zip code of the person that receives the invoice.
legalAddress.citystringThe city of the person that receives the invoice.
legalAddress.countryCodestringThe country code the person that receives the invoice.

Create Approved Legal Address

approvedlegaladdress is only available in Sweden

The approvedlegaladdress resource represents the necessary information that you need to send, to the organization handling national population register information, in order to retrieve the approved legal address of the payer of an invoice payment.

To create an approved legal address by retrieving data from the population register (administered by SPAR in Sweden and DSF in Norway), you need to perform the create-approved-legal-address operation.

Please note: If you have retrieved the legal address by other means, you don't need to execute this operation. 

Request
POST /psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/approvedlegaladdress/ HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "addressee": {
       "socialSecurityNumber": "600307-1161",
       "zipCode": "19792"
    }
}

Properties

PropertyData typeRequiredDescription
addressee.socialSecurityNumberstringYThe social security number (national identity number) of the consumer. Format: Norway DDMMYYXXXXX, Sweden: YYYYMMDDXXXX
addressee.zipCodestringYThe postal code (ZIP code) of the consumer.

Response

Repsonse

HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "approvedLegalAddress": {
       "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/approvedlegaladdress",
       "addressee": "firstName + lastName",
       "coAddress": "coAddress",
       "streetAddress": "streetAddress",
       "zipCode": "zipCode",
       "city": "city",
       "countryCode": "countryCode"
    }
}

Create Invoice Payment

Within the invoice payments part of the eCommerce API, you can initiate an invoice payment with three different Operations, which make use of different invoice types depending on country of operation. 

OperationinvoiceTypeDescription
FinancingConsumerPayExFinancingSe, PayExFinancingNo, PayExFinancingFiInitiates PayEx' Invoice financing process (PayEx Invoice). The invoice type must match country of operation.

Posting a payment is always followed up by a authorization transaction and later captures, cancellations or reversals.

To create a  invoice payment, you perform an HTTP POST against the /psp/invoicepayments resource. Please read the general information on how to compose a valid HTTP request before proceeding.

FinancingConsumer

To create a FinancingConsumer invoice payment (aka "PayEx Invoice"), you need to perform the following request. Use the expand request parameter to get a response that includes one or more expanded sub-resources inlined.

Request
POST /psp/invoice/payments/ HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "payment": {
       "operation": "FinancingConsumer",
       "intent": "Authorization",
       "currency": "NOK|SEK|...",
       "prices": [{
           "type": "Invoice",
           "amount": 1500,
           "vatAmount": 0
        }],
       "description": "Test Purchase",
       "payerReference": "SomeReference",
       "userAgent": "Mozilla/5.0...",
       "language": "nb-NO|sv-SE|...",
       "urls": {
           "completeUrl": "https://example.com/payment-completed",
           "cancelUrl": "https://example.com/payment-canceled",
           "callbackUrl": "https://example.com/payment-callback",
           "hostUrls": ["https://example.com", "https://example.net"],
           "logoUrl": "https://example.com/logo.png",
           "termsOfServiceUrl": "https://example.com/terms.pdf"
        },
       "payeeInfo": {
           "payeeId": "12345678-1234-1234-1234-123456789012",
           "payeeReference": "PR123",
           "payeeName": "Merchant1",
           "productCategory": "PC1234",
           "orderReference": "or-12456",
           "subsite": "MySubsite"
        }
    },
   "invoice": {
       "invoiceType": "PayExFinancingSe|PayExFinancingNo|PayExFinancingFi"
    }
}

Properties

PropertyData typeRequiredDescription
payment.operationstringYFinancingConsumer (use this for PayEx Invoice)
payment.intentstringYAuthorization
payment.currencystringYSEK or NOK
payment.prices.typestringYInvoice
payment.prices.amountnumericYAmount is entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
payment.price.vatAmountnumericYIf the amount given includes VAT, this may be displayed for the user in the payment page (redirect only). Set to 0 (zero) if this is not relevant.
payment.descriptionstring(40)YA textual description max 40 characters of the purchase.
payment.payerReferencestringNThe reference to the payer (consumer/end-user) from the merchant system, like mobile number, customer number etc.
payment.userAgentstringYThe user agent reference of the consumer's browser - see user agent definition
payment.languagestringYnb-NO | sv-SE | en-US
payment.urls.completeUrlstringNIn re-direct model: Enter a URI that PayEx will redirect back to when the payment page is completed.
In direct model: Leave this empty - not in use in direct model.
payment.urls.cancelUrlstringN

In re-direct model: Enter a URI that PayEx will redirect back to when when the user presses the cancel button in the payment page.
In direct model: Leave this empty - not in use in direct model.

payment.urls.callbackUrlstringNA URI that PayEx will post data to when a change to a payment is done
payment.urls.logoUrlstringNThe URI that will be used for showing the customer logo. Must be a picture with at most 50px height and 400px width. Require https.
payment.urls.termsOfServiceUrlstringNA URI that contains your terms and conditions for the payment, to be linked on the payment page. Require https.
payment.payeeInfo.payeeIdstringYThis is the unique id that identifies this payee (like merchant) set by PayEx
payment.payeeInfo.payeeReferencestring(50)YA unique reference max 50 characters set by the merchant system) - this must be unique for each operation! The payeeReference must follow the regex pattern [\w]* (a-zA-Z0-9_).
payment.payeeInfo.payeeNamestringNThe payee name (like merchant name) that will be displayed to consumer when redirected to PayEx
payment.payeeInfo.productCategorystringNA product category or number sent in from the payee/merchant. This is not validated by PayEx, but will be passed through the payment process and may be used in the settlement process
payment.payeeInfo.orderReferencestring(50)NThe order reference shoud reflect the order reference found in the merchant's systems.
payeeInfo.subsiteString(40)NThe subsite field can be used to perform split settlement on the payment. The subsites must be resolved with PayEx reconciliation before being used.
payment.invoice.invoiceTypestringYPayExFinancingSe, PayExFinancingNo or PayExFinancingFi depending on which country you're doing business with PayEx in.
(Other external financing partner names must be agreed upon with PayEx.)
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": {
       "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
       "number": 1234567890,
       "instrument": "Invoice",
       "created": "YYYY-MM-DDThh:mm:ssZ",
       "updated": "YYYY-MM-DDThh:mm:ssZ",
       "state": "Ready|Pending|Failed|Aborted",
       "operation": "FinancingConsumer",
       "intent": "Authorization",
       "currency": "NOK|SEK|...",
       "amount": 1500,
       "remainingCaptureAmount": 1000,
       "remainingCancellationAmount": 1000,
       "remainingReversalAmount": 500,
       "description": "Test Purchase",
       "userAgent": "Mozilla/5.0...",
       "language": "nb-NO",
       "prices": {
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/prices"
        },
       "transactions": {
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions"
        },
       "authorizations": {
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations"
        },
       "captures": {
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/captures"
        },
       "reversals": {
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversals"
        },
       "cancellations": {
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/cancellations"
        },
       "payeeInfo": {
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo"
        },
       "urls": {
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/urls"
        },
       "settings": {
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/settings"
        }
    },
   "approvedLegalAddress": {
       "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/approvedlegaladdress"
    },
   "operations": [{
           "href": "https://api.externalintegration.payex.com/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
           "rel": "abort-payment",
           "method": "PATCH"
        },
        {
           "href": "https://api.externalintegration.payex.com/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations",
           "rel": "create-authorization",
           "method": "POST"
        },
        {
           "href": "https://api.externalintegration.payex.com/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/approvedlegaladdress",
           "rel": "create-approved-legal-address",
           "method": "POST"
        }
    ]
}

Operations

When a payment resource is created and during its lifetime, it will have a set of operations that can be performed on it. Which operations are available will vary depending on the state of the payment resource, what the access token is authorized to do, etc. A list of possible operations and their explanation is given below.

Operations
{
   "payment": {},
   "operations": [
        {
           "href": "http://api.externalintegration.payex.com/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
           "rel": "update-payment-abort",
           "method": "PATCH"
        },
        {
           "href": "http://api.externalintegration.payex.com/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations",
           "rel": "create-authorization",
           "method": "POST"
        },
        {
           "href": "https://ecom.externalintegration.payex.com/invoice/payments/authorize/123456123412341234123456789012",
           "rel": "redirect-authorization",
           "method": "GET"
        },
        {
           "href": "https://api.externalintegration.payex.com/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/captures",
           "rel": "create-capture",
           "method": "POST"
        },
        {
           "href": "https://api.externalintegration.payex.com/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/cancellations",
           "rel": "create-cancellation",
           "method": "POST"
        },
        {
           "href": "https://api.externalintegration.payex.com/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversals",
           "rel": "create-reversal",
           "method": "POST"
        }
    ]
}

Properties

Property Description
hrefThe target URI to perform the operation against.
relThe name of the relation the operation has to the current resource.
methodThe HTTP method to use when performing the operation.

The operations should be performed as described in each response, and not as described in the documentation. The examples here is for documentation purpose only. Always use the href and method  as specified for each available operation, as specified in the response. Every operation have a rel value that describe its relation to the current resource. The only thing that should be hard coded in the client is the value of the rel and the request, that will be sent in the HTTP body of the request for a given operation.

Operation Description
update-payment-abortAborts the payment before any financial transactions are performed.
create-authorizationCreate an authorization transaction.
redirect-authorizationUsed to redirect the consumer to the card authorization UI.
create-captureCreates a capture transaction.
create-cancellationCreates a cancellation transaction.
create-reversalCreates a reversal transaction.

Invoice transactions

All Invoice specific transactions are described below. Read more about the general transaction resource here.

Authorizations

The authorizations resource will list the authorization transactions made on a specific payment.

Request
GET /psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "authorizations": {
       "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations",
       "authorizationList": [{
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations/12345678-1234-1234-1234-123456789012",
           "consumer": {
               "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/consumer"
            },
           "legalAddress": {
               "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/legaladdress"
            },
           "billingAddress": {
               "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/billingaddress"
            },
           "transaction": {
               "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/12345678-1234-1234-1234-123456789012",
               "created": "2016-09-14T01:01:01.01Z",
               "updated": "2016-09-14T01:01:01.03Z",
               "type": "Authorization",
               "state": "Initialized|Completed|Failed",
               "number": 1234567890,
               "amount": 1000,
               "vatAmount": 250,
               "description": "Test transaction",
               "payeeReference": "AH123456",
               "failedReason": "",
               "isOperational": false,
               "operations": [{
                   "href": "https://api.payex.com/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
                   "rel": "edit-authorization",
                   "method": "PATCH"
                }]
            }
        }]
    }
}

Create Authorization transaction

To create an authorization transaction, perform the create-authorization operation as returned in a previously created invoice payment.

Request
POST /psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "transaction": {
       "activity": "FinancingConsumer"
    },
   "consumer": {
       "socialSecurityNumber": "socialSecurityNumber",
       "customerNumber": "customerNumber",
       "name": "consumer name",
       "email": "email",
       "msisdn": "msisdn",
       "ip": "consumer ip address"
    },
   "legalAddress": {
       "addressee": "firstName + lastName",
       "coAddress": "coAddress",
       "streetAddress": "streetAddress",
       "zipCode": "zipCode",
       "city": "city",
       "countryCode": "countryCode"
    },
   "billingAddress": {
       "addressee": "firstName + lastName",
       "coAddress": "coAddress",
       "streetAddress": "streetAddress",
       "zipCode": "zipCode",
       "city": "city",
       "countryCode": "countryCode"
    }
}

Properties

PropertyData typeRequiredDescription
transaction.activitystringYFinancingConsumer
consumer.socialSecurityNumberstringYThe social security number (national identity number) of the consumer. Format Sweden: YYMMDD-NNNN. Format Norway: DDMMYYNNNNN.
consumer.customerNumberstringNThe customer number in the merchant system.
consumer.emailstringNThe e-mail address of the consumer.
consumer.msisdnstringYThe mobile phone number of the consumer. Format Sweden: +46707777777. Format Norway: +4799999999.
consumer.ipstringYThe IP address of the consumer.
legalAddress.addresseestringYThe full (first and last) name of the consumer.
legalAddress.coAddressstringNThe CO-address (if used)
legalAddress.streetAddressstringNThe street address of the consumer.
legalAddress.zipCodestringYThe postal code (ZIP code) of the consumer.
legalAddress.citystringYThe city to the consumer.
legalAddress.countryCodestringYSE or NO. The country code of the consumer.

Note: The legal address must be the registered address of the consumer. 

The authorization resource will be returned, containing information about the newly created authorization transaction.

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "authorization": {
       "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations/12345678-1234-1234-1234-123456789012",
       "consumer": {
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/consumer"
        },
       "legalAddress": {
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/legaladdress"
        },
       "billingAddress": {
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/billingaddress"
        },
       "transaction": {
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/12345678-1234-1234-1234-123456789012",
           "created": "2016-09-14T01:01:01.01Z",
           "updated": "2016-09-14T01:01:01.03Z",
           "type": "Authorization",
           "state": "Initialized|Completed|Failed",
           "number": 1234567890,
           "amount": 1000,
           "vatAmount": 250,
           "description": "Test transaction",
           "payeeReference": "AH123456",
           "failedReason": "",
           "isOperational": "TRUE|FALSE",
           "operations": [{
               "href": "https://api.payex.com/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c"
               "rel": "edit-authorization",
               "method": "PATCH"
            }]
        }
    }
}

Captures

The captures resource list the capture transactions performed on a specific invoice payment.

Request
GET /psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/captures HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "captures": [{
       "itemDescriptions": {
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/5adc265f-f87f-4313-577e-08d3dca1a26c/itemdescriptions"
        },
       "invoiceCopy": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/captures/5adc265f-f87f-4313-577e-08d3dca1a26c/invoicecopy",
       "transaction": {
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/5adc265f-f87f-4313-577e-08d3dca1a26c",
           "created": "2016-09-14T01:01:01.01Z",
           "updated": "2016-09-14T01:01:01.03Z",
           "type": "Capture",
           "state": "Initialized|Completed|Failed",
           "number": 1234567890,
           "amount": 1000,
           "vatAmount": 250,
           "description": "Test transaction",
           "payeeReference": "AH123456",
           "failedReason": "",
           "isOperational": "TRUE|FALSE",
           "operations": []
        }
    }]
}

Create FinancingConsumer capture

To capture a FinancingConsumer invoice payment, perform the create-capture operation with the following request  body:

Request
POST /psp/invoice/payments/<paymentId>/captures HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "transaction": {
       "activity": "FinancingConsumer",
       "amount": 13500,
       "vatAmount": 2500,
       "payeeReference": "customer reference-unique",
       "description": "description for transaction",
       "itemDescriptions": [
          {
           "amount": 12500,
           "description": "item description 1"
          },
          {
           "amount": 1000,
           "description": "item description 2"
          }
        ],
       "vatSummary": [
          {
           "amount": 12500,
           "vatPercent": 2500,
           "vatAmount": 2500
          },
          {
           "amount": 1000,
           "vatPercent": 0,
           "vatAmount": 0
          }
        ]
  }
}
Parameter name DatatypeRequiredValue (with description)
transaction.activitystringYFinancingConsumer.
transaction.AmountintegerYAmount entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
transaction.vatAmountintegerAmount entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
transaction.payeeReferencestring(50)YA unique reference max 50 characters set by the merchant system) - this must be unique for each operation! The payeeReference must follow the regex pattern [\w]* (a-zA-Z0-9_).
transaction.descriptionstringA textual description of the capture
itemDescriptions.amountintegerYTotal price for this order line - entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
itemDescriptions.descriptionstringYA textual description of this product
vatSummary.amountintegerYTotal price for this order line - entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
vatSummary.vatAmountintegerYVAT Amount entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
vatSummary.vatPercentstringYThe VAT in percent. Supported values : "0.00", "6.00", "8.00", "10.00", "12.00", "14.00", "15.00", "22.00", "24.00", "25.00"

Notes on FinancingConsumer captures:

  • Due date is set by PayEx based on the agreement with merchant. Standard due date is 14 days.
  • Invoice number is set by PayEx.
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "capture": {
       "itemDescriptions": {
           "id": "/psp/invoice/payments/<captureId>/transactions/12345678-1234-1234-1234-123456789012/itemDescriptions"
        },
       "invoiceCopy": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/captures/12345678-1234-1234-1234-123456789012/invoicecopy",
       "transaction": {
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/12345678-1234-1234-1234-123456789012",
           "created": "2016-09-14T01:01:01.01Z",
           "updated": "2016-09-14T01:01:01.03Z",
           "type": "Capture",
           "state": "Completed",
           "number": 1234567890,
           "amount": 1000,
           "vatAmount": 250,
           "description": "Test transaction",
           "payeeReference": "AH123456",
           "failedReason": "",
           "isOperational": "TRUE|FALSE",
           "operations": []
        }
    }
}

Properties

PropertyData typeDescription
paymentstringThe relative URI of the payment this capture transaction resource belongs to.
capture.itemDescriptions.idstringThe relative URI of the item descriptions resource associated with this capture transaction resource.
capture.invoiceCopystringThe relative URI of the downloadable invoice copy in PDF format.
capture.transactionobject

The object representation of the transaction resource.

{{/comment}}

Cancellations

The cancellations resource lists the cancellation transactions made on a specific payment.

Request
GET /psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/cancellations HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "cancellations": [{
       "transaction": {
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/5adc265f-f87f-4313-577e-08d3dca1a26c",
           "created": "2016-09-14T01:01:01.01Z",
           "updated": "2016-09-14T01:01:01.03Z",
           "type": "Cancellation",
           "state": "Failed",
           "number": 1234567890,
           "amount": 1000,
           "vatAmount": 250,
           "description": "Test transaction",
           "payeeReference": "AH123456",
           "failedReason": "",
           "isOperational": false,
           "operations": []
        }
    }]
}
PropertyData typeDescription
paymentstringThe relative URI of the payment this list of cancellation transactions belong to.
cancellations.idstringThe relative URI of the current cancellations resource.
cancellations.cancellationListarrayThe array of the cancellation transaction objects.
cancellations.cancellationList[]objectThe object representation of the cancellation transaction resource described below.

Create cancellation transaction

Perform the create-cancellation operation to cancel a previously created - and not yet captured - invoice payment.

Request

POST /psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/cancellations HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "transaction": {
       "activity": "FinancingConsumer",
       "payeeReference": "customer order reference-unique",
       "description": "description for transaction"
    }
}
Parameter name DatatypeRequiredValue (with description)
transaction.activitystringYFinancingConsumer.
transaction.payeeReferencestringYA unique reference max 50 characters set by the merchant system) - this must be unique for each operation! The payeeReference must follow the regex pattern [\w]* (a-zA-Z0-9_)
transaction.descriptionstring(50) A textual description for the cancellation.

The cancel resource will be returned, containing information about the newly created cancellation transaction.

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "cancellation": {
       "transaction": {
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/12345678-1234-1234-1234-123456789012",
           "created": "2016-09-14T01:01:01.01Z",
           "updated": "2016-09-14T01:01:01.03Z",
           "type": "Cancellation",
           "state": "Completed",
           "number": 1234567890,
           "amount": 1000,
           "vatAmount": 250,
           "description": "Test transaction",
           "payeeReference": "AH123456",
           "failedReason": "",
           "isOperational": false,
           "operations": []
        }
    }
}

Properties

PropertyData typeDescription
paymentstringThe relative URI of the payment this capture transaction belongs to.
reversal.idstringThe relative URI of the created capture transaction.
reversal.transactionobjectThe object representation of the generic transaction resource.

Reversals

The reversals resource will list the reversal transactions (one or more) on a specific payment.

Request
GET /psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversals HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "reversal": [{
       "transaction": {
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/12345678-1234-1234-1234-123456789012",
           "created": "2016-09-14T01:01:01.01Z",
           "updated": "2016-09-14T01:01:01.03Z",
           "type": "Reversal",
           "state": "Completed",
           "number": 1234567890,
           "amount": 1000,
           "vatAmount": 250,
           "description": "Test transaction",
           "payeeReference": "AH123456",
           "failedReason": "",
           "isOperational": false,
           "operations": []
        }
    }]
}

Properties

PropertyTypeDescription
paymentstringThe relative URI of the payment that the reversal transactions belong to.
reversalListarrayThe array of reversal transaction objects.
reversalList[]objectThe reversal transaction object representation of the reversal transaction resource described below.

Create reversal transaction

The create-reversal operation will reverse a previously captured payment. To reverse a payment, perform the create-reversal operation. The HTTP body of the request should look like the following.

Request

POST /psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversals HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json

{
   "transaction": {
       "activity": "FinancingConsumer",
       "amount": 1500,
       "vatAmount": 0,
       "payeeReference": "customer reference-unique",
       "description": "description for transaction"
    }
}

Properties

PropertyData typeRequiredDescription
transaction.activitystringYFinancingConsumer.
transaction.amountintegerYAmount Entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
transaction.vatAmountintegerYAmount Entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
transaction.payeeReferencestring(50)A unique reference max 50 characters set by the merchant system) - this must be unique for each operation! The payeeReference must follow the regex pattern [\w]* (a-zA-Z0-9_).
transaction.descriptionstringYA textual description of the reversal.

The reversal resource will be returned, containing information about the newly created reversal transaction.

Response
HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "reversal": {
       "transaction": {
           "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/12345678-1234-1234-1234-123456789012",
           "created": "2016-09-14T01:01:01.01Z",
           "updated": "2016-09-14T01:01:01.03Z",
           "type": "Reversal",
           "state": "Completed",
           "number": 1234567890,
           "amount": 1000,
           "vatAmount": 250,
           "description": "Test transaction",
           "payeeReference": "AH123456",
           "failedReason": "",
           "isOperational": false,
           "operations": []
        }
    }
}

Properties

PropertyData typeDescription
paymentstringThe relative URI of the payment this capture transaction belongs to.
reversal.idstringThe relative URI of the created capture transaction.
reversal.transactionobjectThe object representation of the generic transaction resource.

Item Descriptions

The itemdescriptions resource contains the item descriptions of a specific invoice payment transaction.

Request
GET /psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/293b348e-1a6f-47e5-b6ba-08d6dd1b081e/itemdescriptions HTTP/1.1
Host: api.payex.com
Authorization: Bearer <MerchantToken>
Content-Type: application/json
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "payment": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "transaction": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/293b348e-1a6f-47e5-b6ba-08d6dd1b081e",
   "itemDescriptions": {
       "id": "/psp/invoice/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions/293b348e-1a6f-47e5-b6ba-08d6dd1b081e/itemdescriptions",
       "itemDescriptionList": [
            {
               "amount": 25000,
               "description": "item description 1"
            },
            {
               "amount": 10000,
               "description": "item description 2"
            }
        ],
       "vatSummary": [
            {
               "amount": 25000,
               "vatPercent": 1200,
               "vatAmount": 5000
             },
             {
                "amount": 10000,
                "vatPercent": 600,
                "vatAmount": 2000
             }
        ]
    }   
}

Callback

When a change or update from the back-end system are made on a payment or transaction, PayEx will perform a callback to inform the payee (merchant) about this update. Callback functionality is explaned in more detail here.

Problem messages

When performing unsuccessful operations, the eCommerce API will respond with a problem message. We generally use the problem message type and status code to identify the nature of the problem. The problem name and description will often help narrow down the specifics of the problem.

For general information about problem messages and error handling, visit error handling and problem details. 

Error types from PayEx Invoice and third parties

All invoice error types will have the following URI in front of type: https://api.payex.com/psp/errordetail/invoice/<errorType>

TypeStatus 
externalerror500No error code
inputerror40010 - ValidationWarning
inputerror40030 - ValidationError
inputerror4003010 - ClientRequestInvalid
externalerror50240 - Error
externalerror50260 - SystemError
externalerror50250 - SystemConfigurationError
externalerror5029999 - ServerOtherServer
forbidden403Any other error code
Created by Fredrik Köhler on 2018/10/26 11:08