../credit-account-acquiring

Integrate to PayEx Credit Account Acquiring API 

The credit account acquiring api contains functions that are used in payment scenarios: online, in-store and offline. Before transactions can be created an account must exists.

1579210007372-351.png


Authorizations

An authorization is made to try to use an account for payment. A successful authorization leads to a reservation on the account, the account is identified through the cardToken or the accountNo. The authorization is not a financial transaction, to make the financial transaction a capture must posted on the authorization.

Post

Request
POST /ledger/credit-account-acquiring/v1/XXX/authorizations HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "sellerAuthorizationTransactionId": "789",
   "sellerNumber": "654",
   "cardToken": "5646735165",
   "accountNo": null,
   "pointOfSale": "Testshop",
   "validToDate": "2019-11-28",
   "authorizationAmount": 300.0,
   "currency": "SEK",
}

Note: Either "card" or "accountNo" must be specified in the post request (not both).

The above example shows an authorization done with a card. All cards are linked to an account, to which the authorization will also be linked.
If an authorization is to be made directly against the account, the parameter "accountNo" should be specified in the post body, instead of "cardToken".

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

{
   "@id": "/ledger/credit-account-acquiring/v1/501/authorization/123",
}


Get

Request
GET /ledger/credit-account-acquiring/v1/XXX/authorizations/123 HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

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

{
   "sellerAuthorizationTransactionId": "789",
   "authorizationId": 123,
   "sellerNumber": "654",
   "cardToken": "546415646315",
   "accountNo": null,
   "pointOfSale": "Testshop",
   "validToDate": "2019-11-28",
   "authorizationAmount": 300.0,
   "remainingAmount" : 150.0,
   "currency": "SEK",
   "@id": "/ledger/credit-account-acquiring/v1/501/authorizations/123",
   "captures": "/ledger/credit-account-acquiring/v1/501/authorizations/123/captures",
   "cancellations": "/ledger/credit-account-acquiring/v1/501/authorizations/123/cancellations",
   "schemaUri": "/ledger/invoice-purchase/v1/PayEx.AR.InvoicePurchase.Api.Resources.Authorizations.Resource",
   "parentHREF": "/",
   "operations": [
        {
           "rel": "create-capture",
           "method": "post",
           "href": "/ledger/credit-account-acquiring/v1/501/authorizations/123/captures"
        },
        {
           "rel": "create-cancellation",
           "method": "post",
           "href": "/ledger/credit-account-acquiring/v1/501/authorizations/123/cancellations"
        }
    ]
}

Resource properties

PropertyData typeFormatDescription
@id stringUri  
sellerAuthorizationTransactionIdstringMaxlength: 50Unique identifier of the specific authorization, generated by seller
authorizationIdstringMaxlength: 6Unique identifier of the authorization, generated by PayEx. Should be stored and must be used in capture
sellerNumberstringMaxlength: 15Identifier of the current seller/merchant
cardTokenstring identifier of the card. The aurhotization is made on the account that the card is linked to
accountNostring identifier of the account
pointOfSalestringMaxlength: 50Name of the location/point/shop of sale, will be returned in reservation resource
validToDatedateISO 8601Capture can not be executed after this date
authorizeAmountdecimalAmountOriginal authorized amount
remainingAmountdecimalAmountAmount left on the authorization that can be captured
currencystringISO 4217 
capturesstringUri 
cancellationsstringUri 

Captures

Post

Request
GET /ledger/credit-account-acquiring/v1/XXX/authorizations/captures  HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "sellerCaptureTransactionId" : "534313",
   "sellerReceiptId": "12345689",
   "additionalReferences":{
       "acquirerBatchId": "fdsfsdfsd",
       "acquirerTransactionId" : "534313",
    },      
   "amount": 200.0
}

Get

Request
GET /ledger/credit-account-acquiring/v1/XXX/authorizations/captures/YYY  HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

List

Request
GET /ledger/credit-account-acquiring/v1/XXX/authorizations/captures HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Resource

Response
HTTP/1.1 201 CREATED
Content-Type: application/json

{
   "description": "stora butiken test, köpref. 12345689",
   "sellerCaptureTransactionId" : "534313",
   "additionalReferences":{
       "acquirerBatchId": "fdsfsdfsd",
       "acquirerTransactionId" : "534313",
    },
   "sellerReceiptId": "12345689",        
   "amount":  200.0,
   "reversals": "/ledger/credit-account-acquiring/v1/501/authorizations/123/captures/852/reversals",
   "@id": "/ledger/credit-account-acquiring/v1/501/authorizations/123/capture/852",
   "parentHREF": "/ledger/credit-account-acquiring/v1/501/authorizations/123",
   "operations": [
        {
           "rel": "create-reversal",
           "method": "post",
           "href": "/ledger/credit-account-acquiring/v1/501/authorizations/123/captures/852/reversal"
        }
    ]
}

Resource properties

PropertyData typeFormatDescription
@id stringUri 
descriptionstringMaxlength: 200Describes the current capture (derives from info sent in the authorization), may be printed on the bill, output only

sellerCaptureTransactionId

stringMaxlength: 50Unique identifier of the capture transaction

additionalReferences.acquirerBatchId

stringMaxlength: 50 
additionalReferences.acquirerTransactionIdstringMaxlength: 50Unique acquirer identifier of the transaction
sellerReceiptIddateISO 8601 
amountdecimal  
reversalsstringUri 

Offline-captures

Offline capture transactions can be used when the point of sales cannot connect to the acquiring api to perform standard authorizations. Offline captures can cause the charged credit account to exceed the account limits. Offline captures are always limited by agreement. Different acquiring terms apply for offline-captures compared to standard authorization -> captures.

Note! This is not a general purpose function. The agreement between the client and PayEx will dictate if the function can be used.

Post

Request
GET /ledger/credit-account-acquiring/v1/XXX/offline-captures  HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "pointOfSale": "stora butiken test, köpref. 12345689",
   "sellerCaptureTransactionId" : "534313",
   "additionalReferences":{
       "acquirerBatchId": "fdsfsdfsd",
       "acquirerTransactionId" : "534313",
    },
   "sellerReceiptId": "12345689",        
   "sellerNumber" : "654",  
   "cardToken" : "1564316498964156",
   "accountToken" : null,
   "captureAmount": 300.0,
   "currency": "SEK",
   "@id" : "/ledger/credit-account-acquiring/v1/501/authorizations/123/captures/852",
   "credits" : "/ledger/credit-account-acquiring/v1/501/authorizations/123/captures/852/credits",
   "schemaUri": "/ledger/invoice-purchase/v1/PayEx.AR.InvoicePurchase.Api.Resources.Authorizations.Resource",
   "parentHREF": "/",
   "operations" : []
}

Note: The resource created from POST calls towards "offline-capture" operation is actually a "capture" resource, not "offline-capture".

Get

Request
GET /ledger/credit-account-acquiring/v1/XXX/authorizations/captures/YYY  HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

List

Request
GET /ledger/credit-account-acquiring/v1/XXX/authorizations/captures HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Resource

See the capture resource

Reversals

Used to reverse a capture transaction

Post

Request
GET /ledger/credit-account-acquiring/v1/XXX/authorizations/captures/YYY/reversals  HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

{
   "additionalReferences":{
       "acquirerBatchId": "fdsfsdfsd",
       "acquirerTransactionId" : "534313",
    },
   "sellerReversalTransactionId" : "534313",
   "amount": 200.0
}

Get

Request
GET /ledger/credit-account-acquiring/v1/XXX/authorizations/captures/YYY/reversals/NNN  HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

List

Request
GET /ledger/credit-account-acquiring/v1/XXX/authorizations/captures/YYY/reversals HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Resource

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

{
   "additionalReferences":{
       "acquirerBatchId": "fdsfsdfsd",
       "acquirerTransactionId" : "534313",
    },
   "sellerReversalTransactionId" : "534313",
   "amount": 200.00,
   "creditedAmount": 200.00,
   "currency": "SEK",
   "@id" : "/ledger/credit-account-acquiring/v1/501/authorizations/123/captures/852/credits/741",
   "parentHREF": "/ledger/credit-account-acquiring/v1/501/authorizations/123/captures/852",
   "operations" : []
}

Resource properties

PropertyData typeFormatDescription
@id stringMaxlength:  
settlementBatchIdstringMaxlength: 50 
sellerReversalTransactionIdstringMaxlength: 50 
amountInclVatdecimal  
creditedAmountInclVatdecimal  
currencydateISO 4217 

Cancellations

Post

Request
GET /ledger/credit-account-acquiring/v1/XXX/authorizations/captures/YYY/cancellations HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Get

Request
GET /ledger/credit-account-acquiring/v1/XXX/authorizations/captures/YYY/cancellations/NNN HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Resource

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

{
"cancellationDate" : "2019-11-20",
"@id" : "/ledger/credit-account-acquiring/v1/501/authorizations/123/cancellations",
"parentHREF" : "/ledger/credit-account-acquiring/v1/501/authorizations/123"
}

List

Request
GET /ledger/credit-account-acquiring/v1/XXX/authorizations/captures/YYY/cancellations HTTP/1.1
Host: -
Authorization: Bearer <Token>
Content-Type: application/json

Resource properties

PropertyData typeFormatDescription
@id stringUri 
cancellationDatedateISO 8601 

Problems

If an error occur or any validation failed, a "problem" response will be returned.
Below is a list of problems that can occur:

HttpStatus 401 Unauthorized

  • Token expired
  • Token invalid
  • SellerNumber does not match token
  • CompanyNumber does not match token

HttpStatus 400 Error

  • Validation: Argument required
  • Validation: Invalid value

HttpStatus 422 Unprocessable entity

  • Authorization declined

HttpStatus 409 Conflict

  • Invoice already authorized
  • Duplicate InvoiceNumber
  • Authorization is cancelled
  • Authorization already captured
  • Authorization has expired
  • Insufficient debited amount XXX

HttpStatus 501 NotImplemented

  • CompanyNumber XXX not configured
  • SellerNumber XXX not configured at PayEx
  • CompanyNumber XXX missing configuration

HttpStatus 404 NotFound

  • Authorization not found

Below is an example of a problem that will be returned if buyer.nationalConsumerIdentifier.value is not valid in the authorization post request.

Response
HTTP/1.1 400 Error
Content-Type: application/problem+json

{
   "Type": "http://[DNS]/ledger/invoice-purchase/problems/validation",
   "Title": "A validation error occurred",
   "Status": 400,
   "Instance": null,
   "Detail": "A validation error occurred. Please fix the problems mentioned in the 'problems' property below.",
   "Problems": [
        {
           "buyer.nationalConsumerIdentifier.value": "Not a valid SE nationalConsumerIdentifier"
        }
    ]
}
Created by David Persson on 2019/12/04 09:40