../credit-account-acquiring

Integrate to PayEx Credit Account Acquiring API 

THIS SECTION IS OBSOLETE

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.

1581023647237-858.png

Changelog

2020-02-03
Renamed parameters
sellerCaptureTransactionId -> sourceCaptureTransactionId
sellerReversalTransactionId -> sourceReversalTransactionId

2020-01-30
Added "refunds" resource to use when reversal is made with card and the original capture cannot be referenced.

2020-01-30
renamed sellerAuthorizationTransactionId to sourceAuthorizationTransactionId

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 authorizations

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

{
   "sourceAuthorizationTransactionId": "789",
   "sellerNumber": "654",
   "cardToken": "5646735165",
   "accountNo": null,
   "pointOfSale": "Testshop",
   "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/XXX/authorization/YYY",
}


Get authorizations

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

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

{
   "sourceAuthorizationTransactionId": "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/XXX/authorizations/NNN",
   "captures": "/ledger/credit-account-acquiring/v1/XXX/authorizations/NNN/captures",
   "cancellations": "/ledger/credit-account-acquiring/v1/XXX/authorizations/NNN/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/XXX/authorizations/NNN/captures"
        },
        {
           "rel": "create-cancellation",
           "method": "post",
           "href": "/ledger/credit-account-acquiring/v1/XXX/authorizations/NNN/cancellations"
        }
    ]
}

Resource properties authorizations

PropertyData typeFormatDescription
@id stringUri  
sourceAuthorizationTransactionIdstringMaxlength: 50Unique identifier of the specific authorization, generated by source (typically the integrating system)
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 captures

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

{
   "sourceCaptureTransactionId" : "534313",
   "sellerReceiptId": "2019-11-28",
   "additionalReferences":{
       "acquirerBatchId": "fdsfsdfsd",
       "acquirerTransactionId" : "534313"
    },      
   "amount": 200.0
}

Get captures

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

List captures

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

Resource captures

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

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

Resource properties captures

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

sourceCaptureTransactionId

stringMaxlength: 50Unique identifier of the capture transaction

additionalReferences.acquirerBatchId

stringMaxlength: 50Used for reconciling acquirer transactions. See RKHA21 section on this page for more information
additionalReferences.acquirerTransactionIdstringMaxlength: 50Unique acquirer identifier of the transaction
sellerReceiptIdstringMaxlength: 50 
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 offline-captures

Request
POST /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",
   "sourceCaptureTransactionId" : "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/XXX/authorizations/NNN/captures/YYY",
   "credits" : "/ledger/credit-account-acquiring/v1/XXX/authorizations/NNN/captures/YYY/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".
Execute GET calls to the capture resource to retreive previously made offline-captures

Get offline-captures

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

List offline-captures

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

Operation offline-captures response

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

{
   "captures" : "/ledger/credit-account-acquiring/v1/XXX/authorizations/NNN/captures/YYY"
}

Refunds

Used to refund a transaction without any reference to it.  

Create refunds

Execute post towards this resource to place the amount on the specified account

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

{
   "pointOfSale": "stora butiken test, köpref. 12345689",
   "cardToken" : "1564316498964156",
   "sellerReceiptId": "12345689",        
   "sellerNumber" : "654",  
   "additionalReferences":{
       "acquirerBatchId": "fdsfsdfsd",
       "acquirerTransactionId" : "534313",
    },
   "sourceRefundTransactionId" : "534312",
   "amount": 200.0,
   "currency": "SEK"
}

Get refunds

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

List refunds

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

Resource refunds

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

{
   "pointOfSale": "stora butiken test, köpref. 12345689",
   "cardToken" : "1564316498964156",
   "sellerReceiptId": "12345689",        
   "sellerNumber" : "654",  
   "additionalReferences":{
       "acquirerBatchId": "fdsfsdfsd",
       "acquirerTransactionId" : "534313",
    },
   "sourceRefundTransactionId" : "534313",
   "amount": 200.00,
   "currency": "SEK",
   "@id" : "/ledger/credit-account-acquiring/v1/XXX/reversals/YYY",
   "parentHREF": "",
   "operations" : []
}

Refunds properties

PropertyData typeFormatDescription
@id stringMaxlength:  

additionalReferences.acquirerBatchId

stringMaxlength: 50Used for reconciling acquirer transactions. See RKHA21 section on this page for more information
additionalReferences.acquirerTransactionIdstringMaxlength: 50Unique acquirer identifier of the transaction
sourceRefundTransactionIdstringMaxlength: 50 
amountdecimal  
currencystringISO 4217 
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
pointOfSalestringMaxlength: 50Name of the location/point/shop of sale, will be returned in reservation resource
sellerReceiptIdstringMaxlength: 50 

Reversals

Used to reverse a capture transaction

Create reversals

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

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

Get reversals

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

List reversals

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

Resource reversals

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

{
   "additionalReferences":{
       "acquirerBatchId": "fdsfsdfsd",
       "acquirerTransactionId" : "534313",
    },
   "sourceReversalTransactionId" : "534313",
   "amount": 200.00,
   "currency": "SEK",
   "@id" : "/ledger/credit-account-acquiring/v1/XXX/authorizations/NNN/captures/YYY/credits/ZZZ",
   "parentHREF": "/ledger/credit-account-acquiring/v1/XXX/authorizations/NNN/captures/YYY",
   "operations" : []
}

Reversals resource properties

PropertyData typeFormatDescription
@id stringMaxlength:  

additionalReferences.acquirerBatchId

stringMaxlength: 50Used for reconciling acquirer transactions. See RKHA21 section on this page for more information
additionalReferences.acquirerTransactionIdstringMaxlength: 50Unique acquirer identifier of the transaction
sourceReversalTransactionIdstringMaxlength: 50 
amountdecimal  
currencystringISO 4217 

Cancellations

Post cancellations

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

Get cancellations

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

Resource cancellations

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

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

List cancellations

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

Resource properties

PropertyData typeFormatDescription
@id stringUri 
cancellationDatedateISO 8601 

RKHA21 format

If the original source for the transactions towards Captures/Reversals/Refunds/Offline-captures is the RKHA21 file the below rules should be used to set the AcquirerBatchId.

AcquirerBatchId = [Processing date][Sender][Cycle]

For the example values in the table below the AcquirerBatchId will be "200206885020".

RKHA21 file header row description

PositionFieldFormatDescriptionExample
1Transaction code2 N01 
3Processing date6 NYYMMDD200206
9Sender4 N"8850" (Babs)8850
13Cycle2 AN10/2020
15Filler26 ANSpace characters 
41Vers.nr/serial number6 NFile serial number 
47Transaction entry1 AN  
48Filler333 ANSpace characters 

The rkha format actually has a 28 character filler at position 13 by default, but for "Babs" the first two positions in this filler are redefined to be "cycle" (position 13 and 14), which leaves the Filler to be 26 characters instead of 28.

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"
        }
    ]
}
Tags:
Created by David Persson on 2019/12/04 09:40