Payment Resources

All instrument APIs share certain core resources. The common properties of these resources is described below. See the technical reference for each payment instrument for specific properties not shared by all APIs.

Payment

The payment resource is central to all payment instruments. All operations that target the payment resource directly produce a response similar to the example seen below. The response given contains all operations that are possible to perform in the current state of the payment. You can use the expand parameter to expand one or more properties relating to the purchase resource (see Expansion).

Request
GET /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/ 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": {
       "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
       "number": 1234567890,
       "created": "2016-09-14T13:21:29.3182115Z",
       "updated": "2016-09-14T13:21:57.6627579Z",
       "state": "Ready",
       "operation": "Purchase",
       "intent": "PreAuthorization",
       "currency": "NOK",
       "amount": 1500,
       "remainingCaptureAmount": 1500,
       "remainingCancellationAmount": 1500,
       "remainingReversalAmount": 0,
       "description": "Test Purchase",
       "payerReference": "AB1234",
       "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
       "userAgent": "Mozilla/5.0...",
       "language": "nb-NO",
       "prices": {
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/prices"
        },
       "payeeInfo": {
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo"
        },
       "urls": {
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/urls"
        },
       "transactions": {
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions"
        },
       "authorizations": {
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/authorizations"
        },
       "captures": {
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/captures"
        },
       "reversals": {
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/reversals"
        },
       "cancellations": {
           "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/cancellations"
        }
    },
   "operations": []
}

Properties

PropertyData typeDescription
payment.idstringThe relative URI of the payment.
payment.numberintegerThe payment number, useful when there's need to reference the payment in human communication. Not usable for programmatic identification of the payment, for that id should be used instead.
payment.createdstringThe ISO-8601 date of when the payment was created.
payment.updatedstringThe ISO-8601 date of when the payment was updated.
payment.statestringReady, Pending, Failed or Aborted. Indicates the state of the payment. This field is only for status display purposes. To
payment.prices.amountintegerAmount is entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
payment.prices.vatAmountintegerIf 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)A textual description of maximum 40 characters of the purchase.
payment.payerReferencestringThe reference to the payer (consumer/end-user) from the merchant system, like e-mail address, mobile number, customer number etc.
payment.generatePaymentTokenbooleanSet this to true if you want to receive a paymentToken for future use in One-Click purchases; otherwise false. The default value is false.
payment.userAgentstringThe user agent string of the consumer's browser.
payment.languagestringnb-NO, sv-SE or en-US
payment.urlsstringThe URI to the urls resource where all URIs related to the payment can be retrieved.
payment.payeeInfostringThe URI to the payeeinfo resource where the information about the payee of the payment can be retrieved.

Prices

The prices resource lists the prices related to a specific payment.

Request
GET /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/prices/ 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/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "prices": {
       "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/prices",
       "priceList": [
            {
               "type": "VISA",
               "amount": 2350,
               "vatAmount": 0
            },
            {
               "type": "MasterCard",
               "amount": 2350,
               "vatAmount": 0
            }
        ]
    }
}

Properties

PropertyData typeDescription
paymentstringThe relative URI of the payment the prices resource belongs to.
prices.idstringThe relative URI of the current prices resource.
prices.priceListarrayThe array of price objects. Note: Even if you specifiy CreditCard in the input message the system will return all your configured card brands instead when you expan the priceList.
prices.priceList[].typestringThe type of the price object.
prices.priceList[].amountintegerAmount is entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
prices.priceList[].vatAmountintegerIf 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.

Prices object types

Each payment instrument have one or more prices object types. This is most relevant when using card based and direct debit payments as each type correspond to a card brand or bank respectively.

Payment InstrumentsTypesDescription
Card paymentsCreditCardThe generic type CreditCard enables all card brands, supported by merchant contract.
VisaVisa
MasterCardMasterCard
AmexAmerican Express
DankortDankort can only be used with currency DKK
DinersDiners Club
FinaxFinax
JcbJCB
IkanoFinansDKIkano Finans Denmark
MaestroMasterCard Maestro
DirectDebit PaymentsDirectdebitThe generic type Directdebit enables all bank types, supported by merchant contract.
SwedbankLVSwedbank Latvia
SwedbankEESwedbank Estonia
SwedbankLTSwedbank Lithuania
SwedbankSESwedbank Sweden (Not yet supported)
AalandFIÅlandsbanken Finland (Not yet supported)
AktiaFIAktia Finland (Not yet supported)
DDBFIDanske Bank Finland (Not yet supported)
HSBSEHandelsbanken Sweden (Not yet supported)
NordeaFINordea Finland (Not yet supported)
NordeaSENordea Sweden (Not yet supported)
OmaFIOma säästöpankki Finland (Not yet supported)
OPFIOP Finland (Not yet supported)
POPFIPOP Pankki (Not yet supported)
SHBFIHandelsbanken Finland (Not yet supported)
SpankkiFIS-Pankki Finland (Not yet supported)
SPFISäästöpankki Finland (Not yet supported)
Invoice PaymentsInvoiceAlways Invoice
MobilePay Online PaymentsMobilepayAlways Mobilepay
Swish PaymentsSwishAlways Swish
Vipps PaymentsVippsAlways Vipps

PayeeInfo

The payeeinfo resource contains information about the payee (i.e. a merchant, a corporation etc) related to a specific payment.

Request
GET /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo 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/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "payeeInfo": {
       "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/payeeInfo",
       "payeeId": "12345678-1234-1234-1234-123456789012",
       "payeeReference": "EN1234",
       "payeeName": "TestMerchant1",
       "productCategory": "EF1234",
       "orderReference": "or-123456"

    }
}

Properties

PropertyData typeDescription
paymentstringThe URI of the payment which the payeeinfo belongs to.
payeeInfo.idstringThe URI of the current payeeinfo resource.
payeeInfo.payeeIdstringThis is the unique id that identifies this payee (like merchant) set by PayEx
payeeInfo.payeeReferencestring(50)A unique reference set by the merchant system. See payeeReference for details.
payeeInfo.payeeNamestringThe payee name (like merchant name) that will be displayed to consumer when redirected to PayEx.
payeeInfo.productCategorystringA 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. You therefore need to ensure that the value given here is valid in the settlement.
payeeInfo.orderReferencestring(50)The order reference should reflect the order reference found in the merchant's systems.

URLs

The urls resource contains the URIs related to a payment, including where the end-user/consumer gets redirected when going forward with or cancelling a payment session, as well as the callback URI that is used to inform the payee (merchant) of changes or updates made to the payment or transaction.

Request
GET /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/urls/ 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/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "urls": {
       "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/urls",
       "completeUrl": "http://example.com/payment-complete",
       "cancelUrl": "http://example.com/payment-canceled",
       "callbackUrl": "http://api.example.com/payment-callback",
       "logoUrl": "http://merchant.com/path/to/logo.png",
       "termsOfServiceUrl": "http://merchant.com/path/to/tems"
    }
}

Properties

PropertyData typeDescription
paymentstringThe relative URI of the payment that the urls resource belongs to.
urls.idstringThe relative URI of the current urls resource.
urls.completeUrlstringThe URI that PayEx will redirect back to when the payment page is completed
urls.cancelUrlstringThe URI that PayEx will redirect back to when the user presses the cancel button in the payment page
urls.callbackUrlstringThe URI that PayEx will perform an HTTP POST against every time a transaction is created on the payment. See callback for details.
urls.logoUrlstringOptional: The URI that will be used for showing the customer logo. Must be a picture with at most 50px height and 400px width. Require https.
urls.termsOfServiceUrlstringA URI that contains your terms and conditions for the payment, to be linked on the payment page.

Transactions

A payment contains sub-resources in the form of transactions. Most operations performed on a payment ends up as a transaction. The different types of operations that alter the state of the payment by creating a transaction is described below.

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

Request
GET /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions 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/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "transactions": {
       "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions",
       "transactionList": [{
           "id": "/psp/creditcard/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 authorization",
           "payeeReference": "PR1004",
           "failedReason": "",
           "isOperational": "TRUE|FALSE",
           "operations": []
        }]
    }
}

Properties

PropertyData typeRequired
paymentstringThe relative URI of the payment this list of transactions belong to.
transactions.idstringThe relative URI of the current transactions resource.
transactions.transactionListarrayThe array of transaction objects.
transactions.transactionList[]objectThe transaction object (described in the transaction resource below).

Transaction

The transaction resource contains the generic details of a transaction on a specific payment. 

When a transaction is created it will have one of three states:

  • Initialized - if there is some error where the source is undeterminable (network failure, etc), the transaction will remain Initialized. The corresponding state of the payment order will in this case be set to pending. No further transactions can be created.
  • Completed - if everything went ok the transaction will follow through to completion..
  • Failed - if the transaction has failed (i.e. a denial from the acquiring bank) it is possible to retry (i.e the consumer tries using another credit card) up to a maximum amount of retries (in that case which the payment order gets the state failed as well). . 
Request
GET /psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c/transactions 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/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
   "transaction": {
       "id": "/psp/creditcard/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": "Initialized",
       "number": 1234567890,
       "amount": 1000,
       "vatAmount": 250,
       "description": "Test transaction",
       "payeeReference": "AH123456",
       "failedReason": "",
       "isOperational": true,
       "operations": []
    }
}

Properties

PropertyData typeDescription
paymentstringThe relative URI of the payment this transaction belongs to.
transaction.idstringThe relative URI of the current transaction resource.
transaction.createdstringThe ISO-8601 date and time of when the transaction was created.
transaction.updatedstringThe ISO-8601 date and time of when the transaction was created.
transaction.typestringIndicates the transaction type.
transaction.statestringInitialized, Completed or Failed. Indicates the state of the transaction.
transaction.numberstringThe transaction number, useful when there's need to reference the transaction in human communication. Not usable for programmatic identification of the transaction, for that id should be used instead.
transaction.amountintegerAmount is entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
transaction.vatAmountintegerIf 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.
transaction.descriptionstringA human readable description of maximum 40 characters of the transaction.
transaction.payeeReferencestringA unique reference for the transaction. See payeeReference for details.
transaction.failedReasonstringThe human readable explanation of why the payment failed.
transaction.isOperationalbooleantrue if the transaction is operational; otherwise false.
transaction.operationsarrayThe array of operations that are possible to perform on the transaction in its current state.
Created by Fredrik Köhler on 2018/10/26 11:08