Private Network Transactions (PNT) API Methods

Pre-authorize a Closed Loop Transaction

This API serves as the authorization for a private network (closed loop) transaction.

Syntax

POST /programs/{programCode}/payments/authorize

Headers

Field	Type	Description
programCode	string (path)	The program code assigned to the partner that the customer will belong
X-GD-RequestId	string (header)	Unique ID in GUID format used for identify the request

Request

Request Body

Payload containing purchase details including merchant, POS and encrypted PAN information.

{
  "messageType": "financialRequest (1200)",
  "paymentInstumentIdentifier": "string",
  "encryptedCardData": {
    "version": "string",
    "ephemeralPublicKey": "string",
    "publicKeyHash": "string",
    "data": "string"
  },
  "transactionIdentifier": "string",
  "systemTraceNumber": "string",
  "transactionCode": "purchase (00)",
  "accountType": "current",
  "posEntryMode": {
    "cardInputCapability": "unknown",
    "cardholderAuthenticationCapability": "noAuth",
    "cardCaptureCapability": "none",
    "operatingEnvironment": "noTerminal",
    "cardholderPresence": "present",
    "cardPresence": "notPresent",
    "cardDataInputMode": "unspecified",
    "cardholderAuthenticationMethod": "notAuth",
    "cardholderAuthenticationEntity": "notAuth",
    "cardDataOutputCapability": "unknown",
    "terminalOutputCapability": "unknown",
    "pinCaptureCapability": "noPin"
  },
  "transactionAmount": 0,
  "transactionCurrency": "USD",
  "transactionFeeAmount": 0,
  "transmissionDateTime": "string",
  "localDateTime": "string",
  "settlementDateTime": "string",
  "acquiringCountryCode": "840",
  "cardSequenceNumber": "000",
  "functionCode": "originalAuthAccurateAmt (100)",
  "messageReasonCode": 0,
  "merchant": {
    "merchantId": "string",
    "merchantName": "string",
    "merchantIndustryCode": "string",
    "merchantIndustryCategory": "string",
    "merchantIndustryDescription": "string",
    "addressLine1": "string",
    "city": "string",
    "postalCode": "string",
    "stateProvReg": "string",
    "country": "string"
  },
  "originalAmount": 0,
  "acquirerId": "string",
  "retrievalReferenceNumber": "string",
  "terminalIdentifier": "string",
  "originalTransactionForReveral": {
    "messageType": "financialRequest (1200)",
    "systemTraceNumber": "string",
    "localDateTime": "string",
    "acquirerId": "string"
  },
  "eCommerceIndicator": "notECommerceTx"
}

Request Parameters

Field	Type	Enum Values	Required	Description
messageType	string		No	Request Message Type
paymentInstumentIdentifier	string		No	GUID returned by Green Dot representing the Payment Instrument
encryptedCardData	container		No	Container for encrypted data
version	string		No	Version of encryption algorithm used
ephemeralPublicKey	string		No	Ephemeral public key
publicKeyHash	string		No	Public key hash
data	string		No	Encrypted data payload
transactionIdentifier	string		No	15 character alphanumber identifier
systemTraceNumber	string		Yes	Sequential Value from Terminal from 000001 - 999999
transactionCode	string (enum)	[ 0 - purchase , 1 - atmWithdrawal, 2 - debitAdjustment, 20 - refund, 22 - creditAdustment ]	No	Transaction code - debits goods and services
accountType	string (enum)	[ checking, savings ]	No	Type of account Default value: checking
posEntryMode	container		No	POS Data
cardInputCapability	string (enum)	[0 - unknown, 1 - manual, 2 - magStripe, 3 - barCode, 4 - ocr, 5 - contactChip, 6 - keyEntry, 7 - contactlessEmv, 8 - contactlessMagStripe ]	No	Contains a code indicating the primary means of getting the card information into the terminal.
cardholderAuthenticationCapability	string (enum)	[ 0 - noAuth, 1 - pin, 2 - eSign, 3 - biometrics, 4 - biographic, 5 - manualSign, 6 - otherManual, 10 - mPosPin ]	No	Contains a code indicating the primary means of verifying the cardholder at this terminal.
cardCaptureCapability	string (enum)	[ 0 - none, 1 - capture ]	No	Contains a code indicating whether the terminal has the ability to capture a card.
operatingEnvironment	string (enum)	[ 0 - noTerminal, 1 - onCardAcceptorAttended, 2 - onCardAcceptorUnAttended, 3 - offCardAcceptorAttended, 4 - offCardAcceptorUnAttended, 5 - onCardholderUnAttended, 6 - offCardholderUnAttended, Z - transit ]	No	Contains a code indicating whether the terminal is attended by the card acceptor and its location.
cardholderPresence	string (enum)	[0 - present, 1 - notPresentUnspecified, 2 - notPresentMailOrder, 3 - notPresentTelephone, 4 - notPresentStandingAuth, 5 - electronicOrder, S - installmentPayment ]	No	Contains a code indicating whether the cardholder is present at the point of service and if not, why not.
cardPresence	string (enum)	[ 0 - notPresent, 1 - present ]	No	Contains a code indicating whether the card is present at the point of service.
cardDataInputMode	string (enum)	[0 - unspecified, 1 - manual, 2 - magStripe, 3 - barCode, 4 - ocr, 5 - contactChip, 6 - keyEntered, 7 - completeMagStripe, 8 - eCommerce, 9 - contactlessEmv, A - contactlessMagStripe, B - voicePan ]	No	Contains a code indicating the method used to input the information from the card to the terminal.
cardholderAuthenticationMethod	string (enum)	[0 - notAuth, 1 - pin, 2 - eSign, 3 - biometrics, 4 - biographic, 5 - manualSign, 6 - otherManual (ex. Driver's License), 8 - eCommerceMobile ]	No	Contains a code indicating the method for verifying the cardholder identity.
cardholderAuthenticationEntity	string (enum)	[0 - notAuth, 1 - chip, 2 - cad, 3 - authorizingAgent, 4 - merchant, 5 - other ]	No	Contains a code indicating the entity verifying the cardholder identity.
cardDataOutputCapability	string (enum)	[ 0 -unknown, 1 - none, 2 - magStripeWrite, 3 - chip ]	No	Contains a code indicating the ability of the terminal to update the card.
terminalOutputCapability	string (enum)	[0 unknown, 1 - none, 2 - print, 3 - display, 4 - printAndDisplay ]	No	Contains a code indicating the ability of the terminal to print or display messages.
pinCaptureCapability	string (enum)	[ 0 -noPin, 1 - pinCapabilityUnknown, 3 - threeChar, 4 - fourChar, 5 - fiveChar, 6 - sixChar, 7 - sevenChar, 8 - eightChar, 9 - nineChar, A - tenChar, B - elevenChar, C - twelveChar, S - verify ]	No	Contains a code indicating the length of PIN that the terminal is capable of capturing.
transactionAmount	number ($double)		No	Transaction amount in local currency.
transactionCurrency	string		Yes	Use USD for all transactions. Default value: USD
transmissionDateTime	string		Yes	DateTime at which the transaction was initiated (in GMT). Format: YYMMDDhhmmss.
localDateTime	string		Yes	DateTime at which customer initiated transaction in timezone of customer. Format: YYMMDDhhmmss.
settlementDateTime	string		Yes	Settlement dateTime that partner adheres to. Format: YYMMDDhhmmss.
acquiringCountryCode	string		No	Acquiring Country code. Default value: 840
cardSequenceNumber	string		No	3-digit sequence number defaulted to 000. Default value: 000
functionCode	string (enum)		No	Indicating the specific purpose of the message like Recurring Payment, Financial Message, Full Reversal, Partial Reversal
messageReasonCode	number		No	4-digit number
merchant	container		No	Card acceptor
merchantId	string		No	15 character alphanumeric string
merchantName	string		No	Name of the merchant
merchantIndustryCode	string (enum)	Category of Merchant like 5812: Eating Places and Restaurants 5462: Bakers 5499: Misc food store 5813: Drinking Places 5814: Fast food Restraurants	No	Card acceptor business code
merchantIndustryCategory	string		No	MCC value examples 5812: Eating Places and Restaurants 5462: Bakers 5499: Misc food store 5813: Drinking Places 5814: Fast food Restraurants
merchantIndustryDescription	string		No	Description of the card acceptor industry
addressLine1	string		No	Address line 1 of the card acceptor as known to the cardholder. Variable length, separated from the remaining data elements and from each other by a backslash ().
city	string		No	City name of the card acceptor as known to the cardholder. Variable length, separated from the remaining data elements and from each other by a backslash ().
postalCode	string		No	Postal code of the card acceptor as know to the cardholder This is in fixed format as shown below: Postal code (ANS 10)
stateProvReg	string		No
country	string		No	Country name of the card acceptor as known to the cardholder
originalAmount	number		No	Mandatory for reversals
acquirerId	string		Yes	Code assigned by the authorizing institution
retrievalReferenceNumber	string		Yes	Referal must provide the RRN of the original transaction. 12 digit alphanumeric
terminalIdentifier	string		Yes	8 character alphanumeric code to uniquely identify a terminal
originalTransactionForReferral	container		No	Original transaction
messageType	string		No	Type of message sent
systemTraceNumber	string		Yes	Sequential Value from Terminal from 000001 - 999999
localDateTime	string		Yes	DateTime at which customer initiated transaction in timezone of customer. Format: YYMMDDhhmmss.
acquirerId	string		Yes	Code assigned by the authorizing institution
eCommerceIndicator	string (enum)	[ 0 - Not an electronic commerce transaction 1 - Single mail/telephone order transaction 2 - Recurring mail/telephone order transaction 3 - Mail/telephone order installment payment 4 - Unknown mail/telephone order transaction 5 - Secure electronic transaction with cardholder certificate 6 - Secure electronic transaction without cardholder certificate 7 - Channel-encrypted electronic commerce transaction 8 - Non-secure electronic commerce transaction 9 - Non-authenticated security transaction that does not comply with secure electronic transaction and the merchant supports secure electronic transaction A - Electronic transaction with digital signature]	No	A one-digit field that contains the e-commerce indicator.

Response

Response Body

{
  "messageType": "financialRequestResponse (1210)",
  "paymentInstrumentIdentifier": "string",
  "transactionIdentifier": "string",
  "systemTraceNumber": "string",
  "retrievalReferenceNumber": "string",
  "transactionAmount": 0,
  "transactionCurrency": "string",
  "approvalCode": "string",
  "actionCode": "string",
  "responseDetails": {
    "code": 0,
    "subCode": 0,
    "description": "string",
    "url": "string"
  },
  "additionalAmount": 0
}

Response Parameters

Field	Type	Required	Description
messageType	string	No	Response of the message type
paymentInstrumentIdentifier	string	Yes	Response of the GUID returned by Green Dot representing the Payment Instrument
transactionIdentifier	string	Yes	Response of the 15 character alphanumber identifier
systemTraceNumber	string	Yes	Sequential Value from Terminal from 000001 - 999999
retrievalReferenceNumber	string	No	Response of the referral that must provide the RRN of the original transaction. 12 digit alphanumeric
transactionAmount	number($double)	No	Response of the transaction amount in local currency.
transactionCurrency	string	Yes	Response for transaction currency. Default value: USD
approvalCode	string	No	Contains the approval code if the tx is approved
actionCode	string	Yes	Fixed length response code, ex. 000 - Approved, 002 - Partial Approve, 116 - Insufficient Funds
responseDetails	container	No	Contains response details
code	integer($int32)	No	Response code
subCode	integer($int32)	No	Response sub code
description	string	No	Response description
url	string	No	Response url
additionalAmount	number	No	Contains cash back, balance amounts, etc

Response Codes

Code	Description
201	Customer profile created successfully
400	When some customer parameter is missing or wrong, see response code reference (SubCode Schema) for all possible response subCodes and descriptions.
401	Unauthorized access, wrong token access or expired
403	Forbidden
500	Server Error
503	Service unavailable, try again later or contact IT support

Get Status of a Closed Loop Transaction

This API serves as the authorization for a private network (closed loop) transaction.

Syntax

GET /programs/{programCode}/payments/{paymentInstrumentIdentifier}/status/{retrievalReferenceNumber}

Headers

Field	Type	Description
X-GD-RequestId	string (header)	Unique ID in GUID format used for identify the request
programCode	string (path)	The program code assigned to the partner that the customer will belong
paymentInstrumentIdentifier	string (path)	PaymentInstrumentIdentifier of the payment device used for the transaction
retrievalReferenceNumber	string (path)	retrievalReferenceNumber of the payment authorized in /payments/authorize API

Response

Response Body

{
  "messageType": "financialRequestResponse (1210)",
  "paymentInstrumentIdentifier": "string",
  "transactionIdentifier": "string",
  "systemTraceNumber": "string",
  "retrievalReferenceNumber": "string",
  "transactionAmount": 0,
  "transactionCurrency": "string",
  "approvalCode": "string",
  "actionCode": "string",
  "responseDetails": {
    "code": 0,
    "subCode": 0,
    "description": "string",
    "url": "string"
  },
  "additionalAmount": 0
}

Response Parameters

Field	Type	Required	Description
messageType	string	No	Response of the message type
paymentInstrumentIdentifier	string	Yes	Response of the GUID returned by Green Dot representing the Payment Instrument
transactionIdentifier	string	Yes	Response of the 15 character alphanumber identifier
systemTraceNumber	string	Yes	Sequential Value from Terminal from 000001 - 999999
retrievalReferenceNumber	string	No	Response of the referral that must provide the RRN of the original transaction. 12 digit alphanumeric
transactionAmount	number($double)	No	Response of the transaction amount in local currency.
transactionCurrency	string	Yes	Response for transaction currency. Default value: USD
approvalCode	string	No	Contains the approval code if the tx is approved
actionCode	string	Yes	Fixed length response code, ex. 000 - Approved, 002 - Partial Approve, 116 - Insufficient Funds
responseDetails		No	Contains response details
code	integer($int32)	No	Response code
subCode	integer($int32)	No	Response sub code
description	string	No	Response description
url	string	No	Response url
additionalAmount	number	No	Contains cash back, balance amounts, etc

Response Codes

Code	Description
200	Payment information returned successfully
400	When some payment's required parameter is missing or wrong, see response code reference (SubCode Schema) for all possible response subCodes and descriptions.
401	Unauthorized access, wrong token access or expired
403	Forbidden
500	Server Error
503	Service unavailable, try again later or contact IT support