NORTH EPX - CUSTOM PAY API

sales

This section includes credit card payment authorization and capture endpoints

Auth and Capture

post /sale

This endpoint authorizes and captures funds within the same transaction, provided the authorization portion is approved and is otherwise able to settle. When an auth and capture transaction is run against an account number, the authorization occurs for the dollar amount of the transaction. Immediately after, the capture automatically occurs so that it will settle during the next settlement window.

Parameters

EPI-Idrequired

string

Example:

1111-222222-3-4

Merchant's unique 4-part key, generated after boarding with processor

EPI-Signaturerequired

string

Example:

0123456789ABCDEF

HMAC of endpoint and payload

Content-Typerequired

string

Example:

application/json

Content type of message

EPI-Trace

string

Unique value defined by merchant to identify transactions. Value is not persisted with transaction and is only good during the current request/response chain

Request Schema

amountrequired

number

Example:

11.12

Positive dollar amount of funds to be moved during the transaction. Decimal point required. Should include any reference field amount such as tipAmount or taxAmount. Should not include any cashback, convenience fee, or surcharge amounts. These will be added to the amount authorized and included in the authAmountRequested field

account

string

Maximum:

30

Example:

4111111111111111

The account number to be acted upon during the transaction

expirationDate

string

Maximum:

4

Example:

2501

Credit card’s expiration date

capture

boolean

Default:

true

When set to true, an authorization and capture is performed. When set to false, only an authorization is performed

cvv2

string

Example:

123

Credit card’s CVV2 number

transaction

integer

Example:

123

Unique user-defined code used to identify a transaction

batchIDrequired

number

Unique number created by the user to identify a batch of transactions

industryTyperequired

string

Enum:

P

M

E

Example:

P

The use of the industryType field allows any Retail, CAT, Banking, ECOM, or MOTO transaction to be sent to the same 4-part key and eliminates the need to use unique terminalNumber(s) configured specifically for each industry type. If the industryType field is not present in the request, the EPX platform will determine the best value to use based on the rest of the items in the request, specifically tranType. The supported values are:
P - Cardholder Pesent (Retail, CAT, Banking) E - Ecommerce M - MOTO

cardEntryMethodrequired

string

Maximum:

1

Enum:

A

B

D

G

H

M

Q

R

X

Z

0

1

2

3

E

Example:

G

Indicates how the card number was entered for the transaction: A—Used when scanning a Bar Code B—OCR D—Used when sending Swiped Track 2 data G—Chip (EMV contact) H—Used when sending Swiped Track 1 data M—Used when sending MICR data Q—Proximity / Contactless MSD non-EMV (Track 1 or Track 2 allowed) R—Proximity / Contactless EMV-based (Track 2 data is required) X—Key Entered MICR or Card Number (Typed in using keyboard or keypad) Z—BRIC/GUID Token Transaction 0—Used when sending Key Entered Card data from MagneSafe 1.x Reader 1—Used when sending Encrypted Track 1 data from MagneSafe 1.x Reader 2—Used when sending Encrypted Track 2 data from MagneSafe 1.x Reader 3—Used when sending Encrypted Track 1 and 2 data from MagneSafe 2.x Reader

orderNumber

string

Maximum:

25

Example:

65421

Order number associated with the transaction on the customer's account. User-defined number that serves the same purpose as the invoiceNumber and referenceNumber fields. The most appropriate field may be used based on the user's business setup.

invoiceNumber

string

Maximum:

25

Example:

ABC-123

Invoice number associated with the transaction on the customer's account. User-defined number that serves the same purpose as the referenceNumber and orderNumber fields. The most appropriate field may be used based on the user's business setup.

address

object

trackData

string

Maximum:

256

Example:

B4111111111111111^CARD/TEST^10121010000012345678

Track data from the credit or debit card. This field works with the cardEntryMethod field and may be in clear text or encrypted based on the card reader used during the transaction. When sending track data, track 1 is to be used when processing a credit card transaction, and track 2 is to be used if track 1 is unavailable or when processing a debit or EBT transaction. In some cases, coding environments will perform a URL post of data to EPX. In these cases Track Data may contain special characters, like ‘%’, ‘+’, or ‘=’, that may need to be URL Encoded so that they are communicated correctly

emvData

string

Maximum:

510

Example:

9F34030200009F260828BF9D3AFCC8DD529F2701809F1008010103A0000000009F37044A BAA8C49F3602008595054040040000820258009F3303E0F8C89F1A0208409F3501229F1E0832323135 333731309F03060000000000009A031504309C01009F02060000000010005F2A0208409F090200025F 3401009F4104000000039F0607A0000000041010

The emvData field contains the request data from the EMV kernel as a variable list of fields and their data in TLV format

referencenumber

string

Maximum:

25

Example:

12345678

Required field for PIN-less Debit transactions that contains the consumer’s account information, such as electrical, telephone, loan, or policy number for the bill that is being paid during the transaction

rentalnumber

string

Maximum:

25

Example:

4512

Reference number associated with the transaction on the customer's account. User-defined number that serves the same purpose as the referenceNumber and orderNumber fields. The most appropriate field may be used based on the user's business setup.

userdata

object

userData is custom data that can be sent with a transaction, such as transaction details. This information will be returned. Up to 10 fields of userData can be added.

taxExempt

string

Maximum:

1

Enum:

Y

N

Example:

Y

Reference field that contains an indication as to whether the transaction is tax exempt. This field assists in qualifying a transaction for Level II processing using the following rule. If a transaction is tax-exempt, there is no need to send a tax amount, and if it is not then the tax amount should be supplied in the taxExempt field. Y—Sending a field with a value of Y indicates that the transaction is tax exempt and the tax amount does not need to be provided for Level II qualification. N—Sending a field with a value of N indicates that the transaction is not tax exempt and the tax amount needs to be provided for Level II qualification.

special

object

enhancedData

array

taxAmount

number

Example:

1.12

Reference field that contains the tax amount which is included in the amount of the transaction. This field does not get added to the Amount field during the transaction, it is only referencing the tax amount already included.

system/tranType

string

pinBlock

string

Example:

2DD950BTA77CAD538FFF9876544510E0Z01A

The data provided within the pinBlock field should be the 16-character hexadecimal encrypted pin block (EPD) followed by the DUKPT key serial number KSN. Depending on the specific PIN entry device (PED) this data may need to be reformatted.

cardID

string

Enum:

0

1

M

P

Example:

P

The cardID field contains the code that represents the industry used for the transaction requested. This field is defined in the Transaction Request Fields. Card Identification Codes • 0—CARDHOLDER PRESENT • 1—CARDHOLDER NOT PRESENT • M—CARDHOLDER PRESENT, Card not readable • P—PIN

​

Capture

post /sale/capture

This endpoint captures the previous pre-authorization. A capture can be performed on the amount equal to or less than the dollar amount of the referenced pre-authorization. This endpoint queries the transaction database to identify an auth.

Parameters

EPI-Idrequired

string

Example:

1111-222222-3-4

Merchant's unique 4-part key, generated after boarding with processor

EPI-Signaturerequired

string

Example:

0123456789ABCDEF

HMAC of endpoint and payload

Content-Typerequired

string

Example:

application/json

Content type of message

EPI-Trace

string

Unique value defined by merchant to identify transactions. Value is not persisted with transaction and is only good during the current request/response chain

capturerequired

boolean

Default:

true

When set to true, an authorization and capture will be performed. When set to false, only an authorization will be performed.

Request Schema

amount

number

Example:

11.12

Positive dollar amount of funds to be moved during the transaction. Decimal point required. Should include any reference field amount such as tipAmount or taxAmount. Should not include any cashback, convenience fee, or surcharge amounts. These will be added to the amount authorized and included in the authAmountRequested field

accountrequired

string

Maximum:

30

Example:

4111111111111111

The account number to be acted upon during the transaction

transaction

integer

Example:

123

Unique user-defined code used to identify a transaction

​

Batch Close

put /batch

This endpoint closes all captured transactions from all open batches.

Parameters

EPI-Idrequired

string

Example:

1111-222222-3-4

Merchant's unique 4-part key, generated after boarding with processor

EPI-Signaturerequired

string

Example:

0123456789ABCDEF

HMAC of endpoint and payload

Content-Typerequired

string

Example:

application/json

Content type of message

EPI-Trace

string

Unique value defined by merchant to identify transactions. Value is not persisted with transaction and is only good during the current request/response chain

​

​

​

​

​

​

​

 

 

 

Capture by BRIC

put /sale/{BRIC}/capture

This endpoint captures a previous pre-authorization by its BRIC token. A capture can be performed on the amount equal to or less than the dollar amount of the referenced pre-authorization.

Parameters

EPI-Idrequired

string

Example:

1111-222222-3-4

Merchant's unique 4-part key, generated after boarding with processor

EPI-Signaturerequired

string

Example:

0123456789ABCDEF

HMAC of endpoint and payload

Content-Typerequired

string

Example:

application/json

Content type of message

EPI-Trace

string

Unique value defined by merchant to identify transactions. Value is not persisted with transaction and is only good during the current request/response chain

BRICrequired

string

Example:

00DXDBWHB6WA5HJ3D71

Token/Unique Transaction ID generated for each financial transaction

Request Schema

amountrequired

number

Example:

11.12

Positive dollar amount of funds to be moved during the transaction. Decimal point required. Should include any reference field amount such as tipAmount or taxAmount. Should not include any cashback, convenience fee, or surcharge amounts. These will be added to the amount authorized and included in the authAmountRequested field

batchIDrequired

number

Unique number created by the user to identify a batch of transactions

transactionrequired

integer

Example:

123

Unique user-defined code used to identify a transaction

industryTyperequired

string

Enum:

P

M

E

Example:

P

The use of the industryType field allows any Retail, CAT, Banking, ECOM, or MOTO transaction to be sent to the same 4-part key and eliminates the need to use unique terminalNumber(s) configured specifically for each industry type. If the industryType field is not present in the request, the EPX platform will determine the best value to use based on the rest of the items in the request, specifically tranType. The supported values are:
P - Cardholder Pesent (Retail, CAT, Banking) E - Ecommerce M - MOTO

cardEntryMethodrequired

string

Maximum:

1

Enum:

A

B

D

G

H

M

Q

R

X

Z

0

1

2

3

E

Example:

G

Indicates how the card number was entered for the transaction: A—Used when scanning a Bar Code B—OCR D—Used when sending Swiped Track 2 data G—Chip (EMV contact) H—Used when sending Swiped Track 1 data M—Used when sending MICR data Q—Proximity / Contactless MSD non-EMV (Track 1 or Track 2 allowed) R—Proximity / Contactless EMV-based (Track 2 data is required) X—Key Entered MICR or Card Number (Typed in using keyboard or keypad) Z—BRIC/GUID Token Transaction 0—Used when sending Key Entered Card data from MagneSafe 1.x Reader 1—Used when sending Encrypted Track 1 data from MagneSafe 1.x Reader 2—Used when sending Encrypted Track 2 data from MagneSafe 1.x Reader 3—Used when sending Encrypted Track 1 and 2 data from MagneSafe 2.x Reader

​

​

​

Incremental Authorization

put /sale/inc/{BRIC}

This endpoint adds a specific amount of money to an AuthorizeOnly transaction and incrementally authorizes a new amount. The original transaction BRIC (EPX Transaction Identifier) is required. The amount in the response example is the additional amount needed. For example, if the initial authorization was $20 and the new amount needs to be $30, the json payload would show an Amount of 10.

Parameters

EPI-Idrequired

string

Example:

1111-222222-3-4

Merchant's unique 4-part key, generated after boarding with processor

EPI-Signaturerequired

string

Example:

0123456789ABCDEF

HMAC of endpoint and payload

Content-Typerequired

string

Example:

application/json

Content type of message

EPI-Trace

string

Unique value defined by merchant to identify transactions. Value is not persisted with transaction and is only good during the current request/response chain

BRICrequired

string

Example:

00DXDBWHB6WA5HJ3D71

Token/Unique Transaction ID generated for each financial transaction

Request Schema

amountrequired

number

Example:

11.12

Positive dollar amount of funds to be moved during the transaction. Decimal point required. Should include any reference field amount such as tipAmount or taxAmount. Should not include any cashback, convenience fee, or surcharge amounts. These will be added to the amount authorized and included in the authAmountRequested field

batchIDrequired

number

Unique number created by the user to identify a batch of transactions

transactionrequired

integer

Example:

123

Unique user-defined code used to identify a transaction

industryTyperequired

string

Enum:

P

M

E

Example:

P

The use of the industryType field allows any Retail, CAT, Banking, ECOM, or MOTO transaction to be sent to the same 4-part key and eliminates the need to use unique terminalNumber(s) configured specifically for each industry type. If the industryType field is not present in the request, the EPX platform will determine the best value to use based on the rest of the items in the request, specifically tranType. The supported values are:
P - Cardholder Pesent (Retail, CAT, Banking) E - Ecommerce M - MOTO

cardEntryMethodrequired

string

Maximum:

1

Enum:

A

B

D

G

H

M

Q

R

X

Z

0

1

2

3

E

Example:

G

Indicates how the card number was entered for the transaction: A—Used when scanning a Bar Code B—OCR D—Used when sending Swiped Track 2 data G—Chip (EMV contact) H—Used when sending Swiped Track 1 data M—Used when sending MICR data Q—Proximity / Contactless MSD non-EMV (Track 1 or Track 2 allowed) R—Proximity / Contactless EMV-based (Track 2 data is required) X—Key Entered MICR or Card Number (Typed in using keyboard or keypad) Z—BRIC/GUID Token Transaction 0—Used when sending Key Entered Card data from MagneSafe 1.x Reader 1—Used when sending Encrypted Track 1 data from MagneSafe 1.x Reader 2—Used when sending Encrypted Track 2 data from MagneSafe 1.x Reader 3—Used when sending Encrypted Track 1 and 2 data from MagneSafe 2.x Reader

​

​

​

​

AVS Sale

post /avs

The account verification transaction is used to validate a customer's account information before running a financial transaction. This is done by sending a $0.00 amount during the transaction. The /avs endpoint requires Account, Expiration Date, Transaction ID, Card Entry Method, and Industry Type in the payload. Optional fields that will help with AVS and validation are Address, Zip Code, and CVV2

Parameters

EPI-Idrequired

string

Example:

1111-222222-3-4

Merchant's unique 4-part key, generated after boarding with processor

EPI-Signaturerequired

string

Example:

0123456789ABCDEF

HMAC of endpoint and payload

Content-Typerequired

string

Example:

application/json

Content type of message

EPI-Trace

string

Unique value defined by merchant to identify transactions. Value is not persisted with transaction and is only good during the current request/response chain

Request Schema

amount

number

Example:

11.12

Positive dollar amount of funds to be moved during the transaction. Decimal point required. Should include any reference field amount such as tipAmount or taxAmount. Should not include any cashback, convenience fee, or surcharge amounts. These will be added to the amount authorized and included in the authAmountRequested field

accountrequired

string

Maximum:

30

Example:

4111111111111111

The account number to be acted upon during the transaction

expirationDaterequired

string

Maximum:

4

Example:

2501

Credit card’s expiration date

batchIDrequired

number

Unique number created by the user to identify a batch of transactions

transactionrequired

integer

Example:

123

Unique user-defined code used to identify a transaction

industryTyperequired

string

Enum:

P

M

E

Example:

P

The use of the industryType field allows any Retail, CAT, Banking, ECOM, or MOTO transaction to be sent to the same 4-part key and eliminates the need to use unique terminalNumber(s) configured specifically for each industry type. If the industryType field is not present in the request, the EPX platform will determine the best value to use based on the rest of the items in the request, specifically tranType. The supported values are:
P - Cardholder Pesent (Retail, CAT, Banking) E - Ecommerce M - MOTO

cardEntryMethodrequired

string

Maximum:

1

Enum:

A

B

D

G

H

M

Q

R

X

Z

0

1

2

3

E

Example:

G

Indicates how the card number was entered for the transaction: A—Used when scanning a Bar Code B—OCR D—Used when sending Swiped Track 2 data G—Chip (EMV contact) H—Used when sending Swiped Track 1 data M—Used when sending MICR data Q—Proximity / Contactless MSD non-EMV (Track 1 or Track 2 allowed) R—Proximity / Contactless EMV-based (Track 2 data is required) X—Key Entered MICR or Card Number (Typed in using keyboard or keypad) Z—BRIC/GUID Token Transaction 0—Used when sending Key Entered Card data from MagneSafe 1.x Reader 1—Used when sending Encrypted Track 1 data from MagneSafe 1.x Reader 2—Used when sending Encrypted Track 2 data from MagneSafe 1.x Reader 3—Used when sending Encrypted Track 1 and 2 data from MagneSafe 2.x Reader

cvv2

string

Example:

123

Credit card’s CVV2 number

address

object


 

Sale with BRIC

post /sale/{BRIC}

The BRIC is being used to reference a previous credit card transactions GUID / Token in the EPX system. Since the EPX BRIC is a unique reference value, there is no need to include the account number and expiration date. If the address and zip code was supplied with the original transaction for the BRIC in use it will be included with the transaction request

Parameters

EPI-Idrequired

string

Example:

1111-222222-3-4

Merchant's unique 4-part key, generated after boarding with processor

EPI-Signaturerequired

string

Example:

0123456789ABCDEF

HMAC of endpoint and payload

Content-Typerequired

string

Example:

application/json

Content type of message

EPI-Trace

string

Unique value defined by merchant to identify transactions. Value is not persisted with transaction and is only good during the current request/response chain

BRICrequired

string

Example:

00DXDBWHB6WA5HJ3D71

Token/Unique Transaction ID generated for each financial transaction

Request Schema

amountrequired

number

Example:

11.12

Positive dollar amount of funds to be moved during the transaction. Decimal point required. Should include any reference field amount such as tipAmount or taxAmount. Should not include any cashback, convenience fee, or surcharge amounts. These will be added to the amount authorized and included in the authAmountRequested field

batchIDrequired

number

Unique number created by the user to identify a batch of transactions

transactionrequired

integer

Example:

123

Unique user-defined code used to identify a transaction

industryTyperequired

string

Enum:

P

M

E

Example:

P

The use of the industryType field allows any Retail, CAT, Banking, ECOM, or MOTO transaction to be sent to the same 4-part key and eliminates the need to use unique terminalNumber(s) configured specifically for each industry type. If the industryType field is not present in the request, the EPX platform will determine the best value to use based on the rest of the items in the request, specifically tranType. The supported values are:
P - Cardholder Pesent (Retail, CAT, Banking) E - Ecommerce M - MOTO

cardEntryMethodrequired

string

Maximum:

1

Enum:

A

B

D

G

H

M

Q

R

X

Z

0

1

2

3

E

Example:

G

Indicates how the card number was entered for the transaction: A—Used when scanning a Bar Code B—OCR D—Used when sending Swiped Track 2 data G—Chip (EMV contact) H—Used when sending Swiped Track 1 data M—Used when sending MICR data Q—Proximity / Contactless MSD non-EMV (Track 1 or Track 2 allowed) R—Proximity / Contactless EMV-based (Track 2 data is required) X—Key Entered MICR or Card Number (Typed in using keyboard or keypad) Z—BRIC/GUID Token Transaction 0—Used when sending Key Entered Card data from MagneSafe 1.x Reader 1—Used when sending Encrypted Track 1 data from MagneSafe 1.x Reader 2—Used when sending Encrypted Track 2 data from MagneSafe 1.x Reader 3—Used when sending Encrypted Track 1 and 2 data from MagneSafe 2.x Reader

​

​

​

​

​

Transaction List

get /sale

This endpoint retrieves a list of transactions based on the merchant's four part key, which is set during onboarding. When called directly, the endpoint will list all transactions specific to that four part key at the terminal level. If the detail property is set to DBA, it will tell the endpoint to return all transactions at the DBA level, essentially using the first three parts of the four part key.

Parameters

EPI-Idrequired

string

Example:

1111-222222-3-4

Merchant's unique 4-part key, generated after boarding with processor

EPI-Signaturerequired

string

Example:

0123456789ABCDEF

HMAC of endpoint and payload

Content-Typerequired

string

Example:

application/json

Content type of message

EPI-Trace

string

Unique value defined by merchant to identify transactions. Value is not persisted with transaction and is only good during the current request/response chain

​

​

​

​

Refund Details by BRIC

get /refund/{BRIC}

This endpoint retrieves details of a specific refund based on the BRIC token (EPX Transaction Identifier) of the refund.

Parameters

EPI-Idrequired

string

Example:

1111-222222-3-4

Merchant's unique 4-part key, generated after boarding with processor

EPI-Signaturerequired

string

Example:

0123456789ABCDEF

HMAC of endpoint and payload

Content-Typerequired

string

Example:

application/json

Content type of message

EPI-Trace

string

Unique value defined by merchant to identify transactions. Value is not persisted with transaction and is only good during the current request/response chain

BRICrequired

string

Example:

00DXDBWHB6WA5HJ3D71

Token/Unique Transaction ID generated for each financial transaction

​

​

​

​

Transaction Details by BRIC

get /sale/{BRIC}

This endpoint retrieves the details for a single transaction based on the BRIC (EPX Transaction Identifier) value.

Parameters

EPI-Idrequired

string

Example:

1111-222222-3-4

Merchant's unique 4-part key, generated after boarding with processor

EPI-Signaturerequired

string

Example:

0123456789ABCDEF

HMAC of endpoint and payload

Content-Typerequired

string

Example:

application/json

Content type of message

EPI-Trace

string

Unique value defined by merchant to identify transactions. Value is not persisted with transaction and is only good during the current request/response chain

BRICrequired

string

Example:

00DXDBWHB6WA5HJ3D71

Token/Unique Transaction ID generated for each financial transaction

​

​

​

Batch Details by Transaction

get /batch/{batchID}

This endpoint retrieves details about a specific batch based on the Batch ID.

Parameters

EPI-Idrequired

string

Example:

1111-222222-3-4

Merchant's unique 4-part key, generated after boarding with processor

EPI-Signaturerequired

string

Example:

0123456789ABCDEF

HMAC of endpoint and payload

Content-Typerequired

string

Example:

application/json

Content type of message

EPI-Trace

string

Unique value defined by merchant to identify transactions. Value is not persisted with transaction and is only good during the current request/response chain

batchIDrequired

integer

Example:

123

Unique number created by the user to identify a batch of transactions

​

​

​

​

​

​

​

 

 

System Availability Check

get /ping

This endpoint performs a general ping into the IPS system to verify our system availability.

Parameters

EPI-Idrequired

string

Example:

1111-222222-3-4

Merchant's unique 4-part key, generated after boarding with processor

EPI-Signaturerequired

string

Example:

0123456789ABCDEF

HMAC of endpoint and payload

Content-Typerequired

string

Example:

application/json

Content type of message

EPI-Trace

string

Unique value defined by merchant to identify transactions. Value is not persisted with transaction and is only good during the current request/response chain

 

 

 

 

 

 

Update BRIC

post /storage/bric/{bric}

This endpoint creates a new transaction BRIC (EPX Transaction Identifier) or updates an existing one within the EPX system, without interaction with the card networks. This transaction type is available for both credit card and ACH.

Parameters

EPI-Idrequired

string

Example:

1111-222222-3-4

Merchant's unique 4-part key, generated after boarding with processor

EPI-Signaturerequired

string

Example:

0123456789ABCDEF

HMAC of endpoint and payload

Content-Typerequired

string

Example:

application/json

Content type of message

EPI-Trace

string

Unique value defined by merchant to identify transactions. Value is not persisted with transaction and is only good during the current request/response chain

BRICrequired

string

Example:

00DXDBWHB6WA5HJ3D71

Token/Unique Transaction ID generated for each financial transaction

Request Schema

accountrequired

string

Maximum:

30

Example:

4111111111111111

The account number to be acted upon during the transaction

expirationDate

string

Maximum:

4

Example:

2501

Credit card’s expiration date

 

 

 

 

Create BRIC

post /storage/bric

The Storage transaction presents the capability to create a new BRIC or update an existing one within the EPX system, without interaction with the card networks. This transaction type is available for both credit card (CC) and ACH.

Parameters

EPI-Idrequired

string

Example:

1111-222222-3-4

Merchant's unique 4-part key, generated after boarding with processor

EPI-Signaturerequired

string

Example:

0123456789ABCDEF

HMAC of endpoint and payload

Content-Typerequired

string

Example:

application/json

Content type of message

EPI-Trace

string

Unique value defined by merchant to identify transactions. Value is not persisted with transaction and is only good during the current request/response chain

Request Schema

accountrequired

string

Maximum:

30

Example:

4111111111111111

The account number to be acted upon during the transaction

expirationDate

string

Maximum:

4

Example:

2501

Credit card’s expiration date

 

 

​