Introduction
Paystation APIs
There are a variety of ways to interact with Paystation using an API call. Below you’ll find information on all of our accepted API calls and transaction types.
Fully hosted (3 party)
Fully hosted, referred to in our API documentation as a 3 Party integration, is when the payment form is hosted on our servers. This is the most common integration type, and most likely to gain bank approval in New Zealand. Use our 3 party APIs to complete most integration types.
There are two ways to reach our payment page in a 3 party integration. You can use a redirect, or an iframe. Our sample code gives options for a redirect or iframe and can be found here.
Merchant hosted (2 party)
Merchant hosted, referred to in our API documentation as a 2 Party integration, is when the payment page is hosted on the merchant’s website.
A merchant hosted (2 party) integration will require bank approval. PCI DSS compliance regulations will need to be met before an integration can go live also. While Paystation are more than happy to assist with a 2 party integration type, it pays to ensure that the merchant has approval for this before undertaking any significant development.
2 party
This secure interface allows you to complete a direct integration between Paystation and a website, platform, or application.
3 party
This HTTP interface allows the customer facing payment page to be hosted on Paystation’s servers. Whilst protecting your customer’s private details it also allows you to participate in the Verified by Visa and MasterCard Securecode fraud reduction schemes, reducing some of the risks of chargebacks. This type of processing is most likely to receive bank approval.
PayMe
PayMe allows for the creation of a payment URL, that includes a form. Once the form is completed and submitted the cardholder is sent through to our hosted payment page. A PayMe link can be either single or multiple use, and supports tokenisation.
Sample code
Paystation sample code is available for 2 party and 3 party integrations and can be found here
Currently we offer sample code for the below languages.
- PHP
- C#
- Java
- NodeJS
- ASP
If you believe you could help us extend our sample code base please contact us here
Errors
Transaction error code set
The Paystation API uses the following error codes:
Codes 0-9 relate to the response code from the ETSL, bank and pago payment systems. Codes 10-26 and 101, 102
and 104 would be identified during data validation, and are Paystation errors.
Error Code | Error Message |
---|---|
-1 | Transaction could not be processed |
0 | Transaction successful |
1 | Transaction Declined - Bank Error |
2 | Bank declined transaction |
3 | Transaction Declined - No Reply from Bank |
4 | Transaction Declined - Expired Card |
5 | Transaction Declined - Insufficient funds |
6 | Transaction Declined - Error Communicating with Bank |
7 | Payment Server Processing Error - Typically caused by invalid input data such as an invalid credit card number. Processing errors can also occur |
8 | Transaction Declined / Transaction Type Not Supported - Transaction Type Not Supported |
9 | Bank Declined Transaction (Do not contact Bank) |
10 | Purchase amount less or greater than merchant values |
11 | Paystation couldn’t create order based on inputs |
12 | Paystation couldn’t find merchant based on merchant ID |
13 | Transaction already in progress |
14 | Transaction could not be found |
18 | Transaction type (TT) not specified |
19 | VPC returned data that is not valid - could have been tampered with! |
20 | POST Response URL does not seem to exist |
22 | Merchant_Ref contains invalid characters |
23 | Merchant Session (ms) contains invalid characters |
24 | 2 Party Transactions are not allowed by this merchant |
25 | URL encoding error |
26 | Invalid Amount |
32 | IP is not allowed |
40 | The type of transaction must have the No Redirect flag set to True |
41 | Card number has failed Luhn check |
101 | Merchant has been disabled |
102 | Browser type not supported |
104 | No return URL for merchant |
108 | Gateway Exception |
110 | Must use POST |
145 | To use Dynamic Return URLs, valid HMAC authentication must also be used. |
Token payments error code set
Future payment transaction errors are a subset of the transaction error code set
Codes 0-9 relate to the response code from the ETSL, bank and pago payment systems. Codes 10-26 and 101, 102
and 104 would be identified during data validation, and are Paystation errors
Error Code | Error Message |
---|---|
27 | Billing token already in use |
30 | Future Payment Token or Card Number is required |
31 | Future Payment Token not loaded |
34 | Future Payment Saved OK |
Refund error code set
Refund transaction errors are a subset of the transaction error code set
Codes 11-18, 33 and 101 would be identified during data validation, and are Paystation generated
errors
Error Code | Error Message |
---|---|
14 | Transaction could not be found |
16 | User not allowed to perform refunds |
17 | Merchant is not allowed to perform refunds |
18 | Transaction type not specified |
33 | Refund Token contains invalid characters |
42 | Refund amount too large |
Auth & capture error code set
Authorisation and capture transaction errors are a subset of the transaction error code set
Error Code | Error Message |
---|---|
35 | Merchant in purchase mode. You must not use auth or capture flags |
36 | Merchant in pre-auth mode. You must specify if the transaction is an authoristation or capture |
Lookup error code set
Lookup Code | Lookup Message | Description |
---|---|---|
00 | Successful | No error – look-up successful |
02 | HMAC Validation failed for account [PAYSTATION_ID] | ... |
01 | Matching transaction not found | The transaction was not found. If you are certain that the transaction exists, it could be the transaction is a result of a ‘found’ transaction, which is not currently searched on quick look-ups. This error also occurs when the pi value is incorrect or the merchants Paystation account has been disabled |
03 | Access denied for user [PAYSTATION_ID] | The IP address for the server or computer making the request is not set up in the Paystation system. Contact the Paystation team requesting your IP to be added to the list of allowed hosts for your Paystation ID |
04 | Internal lookup error | .... |
Extended error code set
If the merchant account is set-up to accept Verify by Visa and SecureCode authenticated transactions, you can ask Paystation to have the extended error codes enabled for your account. These codes are in addition to the error result codes above and give information about specifically authentication errors.
Error Code | Error Message |
---|---|
A | Transaction Aborted |
C | Transaction Cancelled |
D | Deferred Transaction |
E | Card Issuer Institution Returned a Referral Response - e.g. Contact details to call bank |
F | 3D Secure Authentication Failed |
I | Card Security Code Failed |
L | Shopping Transaction Locked (This indicates that there is another transaction taking place using the same shopping transaction number) |
N | Cardholder is not enrolled in 3D Secure (Authentication Only) |
P | Transaction is Pending |
R | Retry Limits Exceeded, Transaction Not Processed |
S | Duplicate OrderInfo used. (This is only relevant for Payment Servers that enforce the uniqueness of this field) |
T | Address Verification Failed |
U | Card Security Code Failed |
V | Address Verification and Card Security Code Failed |
Y | Cardholder is not enrolled in 3D Secure |
? | Response Unknown |
HMAC error code set
In addition to all standard error messages, when using HMAC authentication you can now receive an error code of 160 (HMAC validation failed).
Error Code | Error Message |
---|---|
28 | Secret Word submitted incorrectly. Please submit using POST. |
29 | Secret is incorrect |
160 | HMAC validation failed |
Transaction
The Transaction Flow
3-Party
The steps to perform when making a payment using the 3 party payment method are:
- Initiate the payment
POST /direct/paystation.dll
- Store everything locally
- Redirect the card holder’s browser to the payment page.
- Card holder will fill in payment details
- Receive a POST response from Paystation containing the completion status of the transaction, you will store the results locally.
- When the card holder’s browser returns to your site interpret the result of transaction and action according to your business rules (issue receipt, send emails, etc).
2-Party
The steps to perform when making a payment using the 2 party payment method are:
- Send the card details and amount through
POST /direct/paysation.dll
- Receive the response containing the status of the completed transaction
Purchase
A purchase is when card details are sent through to Paystation with a payment amount in a transaction request. Paystation will respond with an error code that reflects either a successful, or an unsuccessful transaction. Our API offers 3 different methods of completing a standard purchase against a credit card.
2 party
Example request
POST https://www.paystation.co.nz/direct/paystation.dll
POST body parameters
paystation=_empty
&pstn_nr=t
&pstn_pi=123456
&pstn_gi=PAYSTATION
&pstn_ms=abcd-defg-hijk
&pstn_am=5000
&pstn_2p=t
&pstn_cn=5555555555554444
&pstn_ex=1705
This endpoint is used to initiate a 2 party transaction
HTTP request
POST https://www.paystation.co.nz/direct/paystation.dll
Required POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
paystation | Transaction initiator flag | Required for payment engine | String value | _empty |
pstn_nr | No Redirect flag | Required for payment engine | Single character "t" or "T" | T |
pstn_pi | Paystation ID | The Paystation ID | String value | 612345 |
pstn_gi | Gateway ID | The Gateway ID | String value | PAYSTATION |
pstn_ms | Merchant Session ID | A unique identifier for every transaction attempt | String value (max 64 chars) | qwertyuiop1234567890 |
pstn_am | Amount | Transaction amount | Integer only, default format is cents | 4200 |
pstn_2p | Two party flag | Required for 2-party transactions | Single character "t" or "T" | T |
pstn_cn | Card number | Credit/debit card number (13 - 19 characters) | Integer, no spaces in between card numbers | 5555555555554444 |
pstn_ex | Card expiry date | Four character expiry date | Integer, no spaces in between year and month (default is yymm format) | 1705 |
Optional POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_cu | Currency | Currency the transaction will be created in | String value | USD |
pstn_tm | Test mode | Used to create a transaction in test mode | Single character "t" or "T" | T |
pstn_mr | Merchant reference | A non-unique identifier that can be assigned to a transaction | String value (max 64 chars) | abc123 |
pstn_ct | Card type | Stating the card type can bypass the card selection screen of a 3-party transaction | String value (max 64 chars) | visa |
pstn_df | Card expiry date format | Defines the format of the expiry date | "mmyy" or "yymm" | mmyy |
pstn_af | Amount format | Defines the format of the amount | String value "dollars.cents" or "cents" | dollars.cents |
pstn_mc | Customer details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_mo | Order details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_cc | Card security code | Three/Four digit code found on back of credit/debit card | String value | 100 |
pstn_rf | Return format | Defines the response format from Paystation (default is XML) | String value | JSON |
Optional query string parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_HMACTimestamp | HMAC Timestamp | The timestamp generated immediately before the request is generated | integer | 1481496738 |
pstn_HMAC | HMAC Hash | A hash of the request, the HMAC timestamp and the HMAC key | string | abc12345 |
HTTP response
The above command returns on SUCCESS an XML response structured like this:
<?xml version="1.0" standalone="yes"?>
<response>
<ec>0</ec>
<em>Transaction successful</em>
<ti>0085789579-01</ti>
<ct>mastercard</ct>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085789579-01</TransactionID>
<PurchaseAmount>5000</PurchaseAmount>
<SurchargeAmount/>
<Locale/>
<ReturnReceiptNumber>85789579</ReturnReceiptNumber>
<ShoppingTransactionNumber/>
<AcqResponseCode>00</AcqResponseCode>
<QSIResponseCode>0</QSIResponseCode>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-13 09:38:26</TransactionTime>
<PaystationErrorCode>0</PaystationErrorCode>
<PaystationErrorMessage>Transaction successful</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<CardNo>555555XXXXXXX444</CardNo>
<CardExpiry>1705</CardExpiry>
<TransactionProcess>purchase</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber>0113</BatchNumber>
<AuthorizeID/>
<Cardtype>MC</Cardtype>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-13 09:38:26</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime>2017-01-13 09:38:26</DigitalReceiptTime>
<PaystationTransactionID>0085789579-01</PaystationTransactionID>
<IssuerName>unknown</IssuerName>
<IssuerCountry>unknown</IssuerCountry>
</response>
The above command returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<response>
<ec>8</ec>
<em>Transaction type not supported</em>
</response>
Attribute | Name | Description | Type | Example |
---|---|---|---|---|
ec | Error code | The error code status of the transaction | integer | 1 |
em | Error message | The error message status of the transaction | string | Transaction successful |
ti | Transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
ct | Card type | The card issuer | string | mastercard |
merchant_ref | A non-unique identifier that can be assigned to a transaction | string | abc123 | |
tm | Test mode | Denotes if the transaction was completed in test mode or not | string | t |
MerchantSession | Merchant Session ID | A unique value to identify a transaction by | string | abcd-defg-hijk |
UsedAcquirerMerchantID | ||||
TransactionID | Transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
PurchaseAmount | Purchase amount | A positive integer in cent value or alternatively the option specified in the transaction representing the charged amount | positive integer or zero | 5000 |
SurchargeAmount | Surcharge amount added to transaction amount | Integer only | default format is cents | 4200 |
Locale | Locale | The language tag represents the language the response text is provided in | ||
ReturnReceiptNumber | Return receipt number | The RRN number is a virtual terminal counter for the transaction and is not unique | positive 8 digit number | 85789579 |
ShoppingTransactionNumber | Shopping transaction number | Is a unique number relating to the Transaction ID (eGate integration's only) | Integer | 85793423 |
AcqResponseCode | Acq response code | Transaction response code from the acquiring bank | Integer | 00 |
QSIResponseCode | QSI response code | Issuing bank response code – the actual raw result from the payment server. Please process transaction result from the PaystationErrorCode | Integer | 0 |
CSCResultCode | CSC result code | The response code in response to verifying the card security code if applicable to transaction | Single character | "M" |
AVSResultCode | AVS result code | Result of any AVS validation. Not supported in New Zealand | Empty | |
TransactionTime | Transaction time | The time the transaction was completed | datetime | 2017-01-13 09:38:26 |
PaystationErrorCode | Error code | The error code status of the transaction | integer | 1 |
PaystationErrorMessage | Error message | The error message status of the transaction | string | Transaction successful |
PaystationExtendedErrorMessage | Extended error message | Extra information regarding the error code if applicable | string value | Refer to card issuer |
MerchantReference | Merchant reference | A non-unique identifier that can be assigned to a transaction | string | abc123 |
CardNo | Card number | A masked card number of the card that completed the transaction | string | 555555XXXXXXX444 |
CardExpiry | Card expiry date | The expiry of the card that completed the transaction | date YYMM | 1705 |
TransactionProcess | Transaction process | The transaction method identification | string | purchase |
TransactionMode | Transaction mode | T or P represents the transaction is a test (T) or production (P) transaction | string value | T |
BatchNumber | Batch number | A four digit number representing the expected settlement date of the transaction in the format MMDD | date MMDD | 0518 |
AuthorizeID | Authorize ID | A unique reference provided by the bank to trace the transaction | string value | R91194 |
Cardtype | Card type | The card issuer | string | MC |
Username | Paystation account ID | The Paystation account ID that initiated the transaction | integer | 123456 |
RequestIP | Request ip | The ip used in the initiation of the request | string | 192.168.1.1 |
RequestUserAgent | Request user agent | String that identifies the application client that initiated the transaction request | string | Mozilla/5.0 |
RequestHttpReferrer | Request http referrer | HTTP referrer header if applicable to original transaction request | string value | https://www.example.com |
PaymentRequestTime | Payment request time | The time the transaction was initiated at | datetime | 2017-01-13 09:38:26 |
DigitalOrderTime | Digital order time | The hosted payment page URL link for the transaction | datetime | 2018-03-11 02:40:16 |
DigitalReceiptTime | Digital receipt time | Timestamp the transaction URL was created (does not apply to 2-party transactions) | datetime | 2018-03-11 02:40:16 |
PaystationTransactionID | Paystation transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
IssuerName | Issuer name | The card issuing institution if known | string | KIWIBANK LIMITED |
IssuerCountry | Issuer country | The country the card was issued if known | string | NEW ZEALAND |
2.5 party
Example request
POST https://www.paystation.co.nz/direct/paystation.dll
POST body parameters
paystation=_empty
&pstn_nr=t
&pstn_pi=123456
&pstn_gi=PAYSTATION
&pstn_ms=abcd-defg-hijk
&pstn_am=5000
&pstn_2p=t
&pstn_VisaCheckoutCallId=12498125876125817625
This endpoint is used to initiate a 2.5 party transaction after the user has selected a card stores with Visa Checkout.
HTTP request
POST https://www.paystation.co.nz/direct/paystation.dll
Required POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
paystation | Transaction initiator flag | Required for payment engine | String value | _empty |
pstn_nr | No Redirect flag | Required for payment engine | Single character "t" or "T" | T |
pstn_pi | Paystation ID | The Paystation ID | String value | 612345 |
pstn_gi | Gateway ID | The Gateway ID | String value | PAYSTATION |
pstn_ms | Merchant Session ID | A unique identifier for every transaction attempt | String value (max 64 chars) | qwertyuiop1234567890 |
pstn_am | Amount | Transaction amount | Integer only, default format is cents | 4200 |
pstn_2p | Two party flag | Required for 2-party transactions | Single character "t" or "T" | T |
pstn_VisaCheckoutCallId | Visa Checkout Call ID | Call ID returned from a successful visa checkout initiation. | Numeric | 12498125876125817625 |
Optional POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_cu | Currency | Currency the transaction will be created in | String value | USD |
pstn_tm | Test mode | Used to create a transaction in test mode | Single character "t" or "T" | T |
pstn_mr | Merchant reference | A non-unique identifier that can be assigned to a transaction | String value (max 64 chars) | abc123 |
pstn_ct | Card type | Stating the card type can bypass the card selection screen of a 3-party transaction | String value (max 64 chars) | visa |
pstn_af | Amount format | Defines the format of the amount | String value "dollars.cents" or "cents" | dollars.cents |
pstn_mc | Customer details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_mo | Order details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_cc | Card security code | Three/Four digit code found on back of credit/debit card | String value | 100 |
pstn_rf | Return format | Defines the response format from Paystation (default is XML) | String value | JSON |
HTTP response
The above command returns on SUCCESS an XML response structured like this:
<?xml version="1.0" standalone="yes"?>
<response>
<ec>0</ec>
<em>Transaction successful</em>
<ti>0085789579-01</ti>
<ct>mastercard</ct>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085789579-01</TransactionID>
<PurchaseAmount>5000</PurchaseAmount>
<SurchargeAmount/>
<Locale/>
<ReturnReceiptNumber>85789579</ReturnReceiptNumber>
<ShoppingTransactionNumber/>
<AcqResponseCode>00</AcqResponseCode>
<QSIResponseCode>0</QSIResponseCode>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-13 09:38:26</TransactionTime>
<PaystationErrorCode>0</PaystationErrorCode>
<PaystationErrorMessage>Transaction successful</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>purchase</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber>0113</BatchNumber>
<AuthorizeID/>
<Cardtype>MC</Cardtype>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-13 09:38:26</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime>2017-01-13 09:38:26</DigitalReceiptTime>
<PaystationTransactionID>0085789579-01</PaystationTransactionID>
<IssuerName>unknown</IssuerName>
<IssuerCountry>unknown</IssuerCountry>
</response>
The above command returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<response>
<ec>8</ec>
<em>Transaction type not supported</em>
</response>
Attribute | Name | Description | Type | Example |
---|---|---|---|---|
ec | Error code | The error code status of the transaction | integer | 1 |
em | Error message | The error message status of the transaction | string | Transaction successful |
ti | Transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
ct | Card type | The card issuer | string | mastercard |
merchant_ref | A non-unique identifier that can be assigned to a transaction | string | abc123 | |
tm | Test mode | Denotes if the transaction was completed in test mode or not | string | t |
MerchantSession | Merchant Session ID | A unique value to identify a transaction by | string | abcd-defg-hijk |
UsedAcquirerMerchantID | ||||
TransactionID | Transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
PurchaseAmount | Purchase amount | A positive integer in cent value or alternatively the option specified in the transaction representing the charged amount | positive integer or zero | 5000 |
SurchargeAmount | Surcharge amount added to transaction amount | Integer only | default format is cents | 4200 |
Locale | Locale | The language tag represents the language the response text is provided in | ||
ReturnReceiptNumber | Return receipt number | The RRN number is a virtual terminal counter for the transaction and is not unique | positive 8 digit number | 85789579 |
ShoppingTransactionNumber | Shopping transaction number | Is a unique number relating to the Transaction ID (eGate integration's only) | Integer | 85793423 |
AcqResponseCode | Acq response code | Transaction response code from the acquiring bank | Integer | 00 |
QSIResponseCode | QSI response code | Issuing bank response code – the actual raw result from the payment server. Please process transaction result from the PaystationErrorCode | Integer | 0 |
CSCResultCode | CSC result code | The response code in response to verifying the card security code if applicable to transaction | Single character | "M" |
AVSResultCode | AVS result code | Result of any AVS validation. Not supported in New Zealand | Empty | |
TransactionTime | Transaction time | The time the transaction was completed | datetime | 2017-01-13 09:38:26 |
PaystationErrorCode | Error code | The error code status of the transaction | integer | 1 |
PaystationErrorMessage | Error message | The error message status of the transaction | string | Transaction successful |
PaystationExtendedErrorMessage | Extended error message | Extra information regarding the error code if applicable | string value | Refer to card issuer |
MerchantReference | Merchant reference | A non-unique identifier that can be assigned to a transaction | string | abc123 |
CardNo | Card number | A masked card number of the card that completed the transaction | string | 555555XXXXXXX444 |
CardExpiry | Card expiry date | The expiry of the card that completed the transaction | date YYMM | 1705 |
TransactionProcess | Transaction process | The transaction method identification | string | purchase |
TransactionMode | Transaction mode | T or P represents the transaction is a test (T) or production (P) transaction | string value | T |
BatchNumber | Batch number | A four digit number representing the expected settlement date of the transaction in the format MMDD | date MMDD | 0518 |
AuthorizeID | Authorize ID | A unique reference provided by the bank to trace the transaction | string value | R91194 |
Cardtype | Card type | The card issuer | string | MC |
Username | Paystation account ID | The Paystation account ID that initiated the transaction | integer | 123456 |
RequestIP | Request ip | The ip used in the initiation of the request | string | 192.168.1.1 |
RequestUserAgent | Request user agent | String that identifies the application client that initiated the transaction request | string | Mozilla/5.0 |
RequestHttpReferrer | Request http referrer | HTTP referrer header if applicable to original transaction request | string value | https://www.example.com |
PaymentRequestTime | Payment request time | The time the transaction was initiated at | datetime | 2017-01-13 09:38:26 |
DigitalOrderTime | Digital order time | The hosted payment page URL link for the transaction | datetime | 2018-03-11 02:40:16 |
DigitalReceiptTime | Digital receipt time | Timestamp the transaction URL was created (does not apply to 2-party transactions) | datetime | 2018-03-11 02:40:16 |
PaystationTransactionID | Paystation transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
IssuerName | Issuer name | The card issuing institution if known | string | KIWIBANK LIMITED |
IssuerCountry | Issuer country | The country the card was issued if known | string | NEW ZEALAND |
3 party
Example request
POST https://www.paystation.co.nz/direct/paystation.dll
POST body parameters
paystation=_empty
&pstn_nr=t
&pstn_pi=123456
&pstn_gi=PAYSTATION
&pstn_ms=abcd-defg-hijk
&pstn_am=5000
This endpoint is used to initiate a 3 party transaction this will return a response that will include a URL for completing a transaction
HTTP request
POST https://www.paystation.co.nz/direct/paystation.dll
Required POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
paystation | Transaction initiator flag | Required for payment engine | String value | _empty |
pstn_nr | No Redirect flag | Required for payment engine | Single character "t" or "T" | T |
pstn_pi | Paystation ID | The Paystation ID | String value | 612345 |
pstn_gi | Gateway ID | The Gateway ID | String value | PAYSTATION |
pstn_ms | Merchant Session ID | A unique identifier for every transaction attempt | String value (max 64 chars) | qwertyuiop1234567890 |
pstn_am | Amount | Transaction amount | Integer only, default format is cents | 4200 |
Optional POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_cu | Currency | Currency the transaction will be created in | String value | USD |
pstn_tm | Test mode | Used to create a transaction in test mode | Single character "t" or "T" | T |
pstn_mr | Merchant reference | A non-unique identifier that can be assigned to a transaction | String value (max 64 chars) | abc123 |
pstn_ct | Card type | Stating the card type can bypass the card selection screen of a 3-party transaction | String value (max 64 chars) | visa |
pstn_df | Card expiry date format | Defines the format of the expiry date | "mmyy" or "yymm" | mmyy |
pstn_af | Amount format | Defines the format of the amount | String value "dollars.cents" or "cents" | dollars.cents |
pstn_mc | Customer details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_mo | Order details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_du | Dynamic Return URL | The URL to re-direct the customer to after a 3-party transaction | URL encoded string value | https://paymentmaker.com/returnurl |
pstn_dp | Dynamic POST Response URL | The URL to send the POST Response to after a 3-party transaction | URL encoded string value | https://paymentmaker.com/postresponseurl |
pstn_rf | Return format | Defines the response format from Paystation (default is XML) | String value | JSON |
HTTP response
The above request returns on SUCCESS an XML response structured like this:
<?xml version="1.0" standalone="yes"?>
<InitiationRequestResponse>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-13 09:41:13</PaymentRequestTime>
<DigitalOrder>https://payments.paystation.co.nz/hosted/?hk=kzh8KrOQBMsLfyhQUDbdbCoLP-wHTUZM</DigitalOrder>
<DigitalOrderTime>2017-01-13 09:41:13</DigitalOrderTime>
<DigitalReceiptTime/>
<PaystationTransactionID>0085789745-01</PaystationTransactionID>
</InitiationRequestResponse>
The above command returns on FAILURE an XML response structured like this:
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<response>
<ec>8</ec>
<em>Transaction type not supported</em>
</response>
Attribute | Name | Description | Type | Example |
---|---|---|---|---|
Username | Paystation account ID | The Paystation account ID that initiated the transaction | integer | 123456 |
RequestIP | Request ip | The ip used in the initiation of the request | string | 192.168.1.1 |
RequestUserAgent | Request user agent | String that identifies the application client that initiated the transaction request | string | Mozilla/5.0 |
RequestHttpReferrer | Request http referrer | HTTP referrer header if applicable to original transaction request | string value | https://www.example.com |
PaymentRequestTime | Payment request time | The time the transaction was initiated at | datetime | 2017-01-13 09:38:26 |
DigitalOrder | Digital order URL | The hosted payment page URL link for the transaction | URL | https://payments.paystation.co.nz/hosted/?hk=12345 |
DigitalOrderTime | Digital order time | The hosted payment page URL link for the transaction | datetime | 2018-03-11 02:40:16 |
DigitalReceiptTime | Digital receipt time | Timestamp the transaction URL was created (does not apply to 2-party transactions) | datetime | 2018-03-11 02:40:16 |
PaystationTransactionID | Paystation transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
PayMe
Example request
POST https://www.paystation.co.nz/direct/paystation.dll
POST body parameters
paystation=_empty
&pstn_nr=t
&pstn_pi=123456
&pstn_gi=PAYSTATION
&pstn_co=t
This endpoint is used to create a PayMe payment URL
HTTP request
POST https://www.paystation.co.nz/direct/paystation.dll
Required POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
paystation | Transaction initiator flag | Required for payment engine | String value | _empty |
pstn_nr | No Redirect flag | Required for payment engine | Single character "t" or "T" | T |
pstn_pi | Paystation ID | The Paystation ID | String value | 612345 |
pstn_gi | Gateway ID | The Gateway ID | String value | PAYSTATION |
pstn_co | PayMe order flag | Required for a PayMe transaction | Single character "t" or "T" | T |
Optional POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_am | Amount | Transaction amount | Integer only, default format is cents | 4200 |
pstn_cu | Currency | Currency the transaction will be created in | String value | USD |
pstn_tm | Test mode | Used to create a transaction in test mode | Single character "t" or "T" | T |
pstn_mr | Merchant reference | A non-unique identifier that can be assigned to a transaction | String value (max 64 chars) | abc123 |
pstn_ct | Card type | Stating the card type can bypass the card selection screen of a 3-party transaction | String value (max 64 chars) | visa |
pstn_df | Card expiry date format | Defines the format of the expiry date | "mmyy" or "yymm" | mmyy |
pstn_af | Amount format | Defines the format of the amount | String value "dollars.cents" or "cents" | dollars.cents |
pstn_mc | Customer details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_mo | Order details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_rf | Return format | Defines the response format from Paystation (default is XML) | String value | JSON |
pstn_tc | Terms and conditions flag | Will add to our hosted page a tick box and a link to the merchants T&Cs | Single character "t" or "T" | T |
pstn_cj | PayMe custom fields | Information and custom fields to be displayed on the PayMe order details page | Url encoded string value of JSON format: {"reference": "PayMe reference","description": "A description for a PayMe example","single": "N"} where reference is your identifier (ie: an invoice number), description is the type of reference, and single (Y/N) denotes single payment |
%7B%22reference%22%3A%20%22PayMe%20reference%22%2C%22description%22%3A%20%22A%20description%20for%20a%20PayMe%20example%22%2C%22single%22%3A%20%22N%22%7D |
HTTP response
The above command returns on SUCCESS an XML response structured like this:
<?xml version="1.0" standalone="yes"?>
<PaystationPayMeOrderCreationResponse>
<PayMeOrderURL>https://payments.paystation.co.nz/pay/ry-3ksghqHg6GA06sgMPnyclUh_FaeANCER7P226hWM</PayMeOrderURL>
<PayMeOrderID>16550</PayMeOrderID>
<ec>0</ec>
<em>Transaction successful</em>
<PaystationErrorCode>0</PaystationErrorCode>
<PaystationErrorMessage>Transaction successful</PaystationErrorMessage>
<RequestIP>192.168.1.1</RequestIP>
</PaystationPayMeOrderCreationResponse>
The above command returns on FAILURE an XML response structured like this:
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<response>
<ec>8</ec>
<em>Transaction type not supported</em>
</response>
Attribute | Name | Description | Type | Example |
---|---|---|---|---|
PayMeOrderURL | PayMe order URL | The hosted payment page URL link for the transaction | URL | https://payments.paystation.co.nz/hosted/?hk=12345 |
PayMeOrderID | PayMe order ID | A unique identifier assigned to each PayMe transaction | integer | 12345 |
ec | Error code | The error code status of the transaction | integer | 1 |
em | Error message | The error message status of the transaction | string | Transaction successful |
PaystationErrorCode | Error code | The error code status of the transaction | integer | 1 |
PaystationErrorMessage | Error message | The error message status of the transaction | string | Transaction successful |
RequestIP | Request ip | The ip used in the initiation of the request | string | 192.168.1.1 |
TXN Confirmation
There are a number of ways you can confirm the transaction response.
Use a GET to redirect from the hosted page (return URL).
A POST response will send the transaction details in an XML packet after we have received the transaction response from the acquiring bank.
A Quick lookup will send a query to Paystation. We will send an XML formatted response once the transaction has been completed. Quick lookup requires IP limiting or HMAC authentication.
Use Dynamic return to control the GET (redirect from the hosted page) and POST response. Dynamic return requires HMAC authentication.
HMAC authentication can be used in lieu of IP limiting for transactions that require it
POST response
After the transaction is processed, the response will be returned to your POST response URL. POST response URLs are either fixed and stored against your Paystation account, or can be dynamic, using our Dynamic return URL.
If you are using a token integration, the response (on token initiator and save only transactions) is sent as a browser redirect in the form of a standard HTTP GET query. You will be able to extract the response values using the standard tools available within your development environment.
POST response addendum
Example POST response XML packet:
<?xml version="1.0" standalone="yes"?>
<PaystationPaymentVerification>
<Username>123456</Username>
<MerchantSession>1168475644.8</MerchantSession>
<UsedAcquirerMerchantID>123456</UsedAcquirerMerchantID>
<TransactionID>0000743943-01</TransactionID>
<PurchaseAmount>7500</PurchaseAmount>
<Locale>en</Locale>
<ReturnReceiptNumber>000000000165</ReturnReceiptNumber>
<ShoppingTransactionNumber>195</ShoppingTransactionNumber>
<AcqResponseCode>00</AcqResponseCode>
<QSIResponseCode>0</QSIResponseCode>
<CSCResultCode>U</CSCResultCode>
<AVSResultCode>U</AVSResultCode>
<TransactionTime>2017-01-11 13:40:33</TransactionTime>
<PaystationErrorCode>0</PaystationErrorCode>
<Authentication>
<auth_Type/>
<auth_Status/>
<auth_SecurityLevel/>
<auth_HashToken/>
<auth_3DSID/>
<auth_3DSElectronicCommerceIndicator/>
<auth_3DSEnrolled/>
<auth_3DSStatus/>
</Authentication>
<BatchNumber>20070111</BatchNumber>
<AuthorizeID>R81194</AuthorizeID>
<Cardtype>MC</Cardtype>
<CustomerIP>222.152.4.143</CustomerIP>
<CustomerUserAgent>Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)</CustomerUserAgent>
<PaymentRequestTime>2017-01-11 13:39:09</PaymentRequestTime>
<PaymentResponseTime>2017-01-11 13:40:33</PaymentResponseTime>
<UserAdditionalVars>
<txn_mode>Liv</txn_mode>
</UserAdditionalVars>
</PaystationPaymentVerification>
POST response is an XML packet that is generated immediately before the customer redirect is issued, and is directed to a pre-defined POST response URL.
In the event of POST response failure, a system generated email will be sent to the authorised email address. This email will list transaction details such as the transaction identifier ti
, the merchant session pstn_ms
, the merchant reference pstn_mr
, date, time, and the POST response error.
HTTP response
After a transaction is processed the POST response will be returned to your Paystation POST response URL (either static or dynamic).
The response is sent from our processing servers as a standard POST request directly to the specified URL. The specified URL must be accessible from the Internet. The response is in the form of XML in the POST body. You will be able to extract the response values using the standard tools available within your development environment.
Parameter | Name | Description | Example |
---|---|---|---|
Username | Paystation User Name | BIN. The first 6 digits of a credit card number | 519163 |
UsedAcquirerMerchantID | Used acquirer merchant id | The acquirer’s merchant ID used for the transaction | integer |
TransactionID | Transaction ID | A string containing the unique transaction ID assigned to the transaction attempt by the Paystation server | string |
PurchaseAmount | Purchase amount | The amount of the transaction, in cents | 4200 |
Locale | Locale | The locale of the transaction. The payment server does support different languages, although this is not currently implemented. Would normally be set to “en” | en |
ReturnReceiptNumber | Return Receipe Number | The RRN number is a virtual terminal counter for the transaction and is not unique | Integer |
ShoppingTransactionNumber | Shopping Transaction Number | Unique bank reference assigned to the transaction | Integer |
AcqResponseCode | Acquirer's Response Code | The result code’s vary from acquirer to acquirer and is included for debugging purposes. Please process transaction result from the PaystationErrorCode | Integer |
QSIResponseCode | QSI Response Code | Payment Server Response code – the actual raw result from the payment server. Please process transaction result from the PaystationErrorCode | Integer |
AVSResultCode | AVS Result Code | Result of any AVS validation. Not supported in New Zealand | Empty |
TransactionTime | Transaction Time | The time the transaction was initiated at Paystation | datetime |
PaystationErrorCode | Paystation Error Code | The result of the transaction | integer |
3DS Authentication Tags
If your transaction needs to be validated by 3DS .....
Parameter | Name | Description | Example |
---|---|---|---|
auth_Type | Authentication Type | This will always be '3DS' | 3DS |
The Authentication status can return numerous responses Y | E | N | U | F | A | D | C | S | P | I
Dynamic return url
Paystation have a Dynamic return API for integration types that require it.
Paystation have a Dynamic return API for integration types that require it.
In a standard Paystation integration, we require the return and POST response URLs to be supplied to Paystation, these are fixed against an account on the gateway. You can provide us with a single URL for return and POST response, or we can have separate URLs for successful/unsuccessful transactions and test/production transactions, along with test/production POST response URLs
Using dynamic return URLs the GET (return URL) and POST (POST response URL) can be specified during the transaction initiation phase of a hosted transaction. These can be varied per transaction, and be controlled completely by the merchants website, rather than being fixed by Paystation.
HTTP response
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_du | Dynamic Return URL | The URL to re-direct the customer to after a 3-party transaction | URL encoded string value | https://paymentmaker.com/returnurl |
pstn_dp | Dynamic POST Response URL | The URL to send the POST Response to after a 3-party transaction | URL encoded string value | https://paymentmaker.com/postresponseurl |
Quick lookup
Request
Example request
GET https://payments.paystation.co.nz/lookup?pi={PAYSTATION_ID}&ti={TXN_ID}
GET query parameters
pi=123456
&ti=0123456789-01
The above command returns on SUCCESS an XML response structured like this:
<PaystationQuickLookup>
<LookupStatus>
<LookupCode>00</LookupCode>
<LookupMessage>Successful</LookupMessage>
<RemoteHostAddress>192.168.1.1</RemoteHostAddress>
</LookupStatus>
<LookupResponse>
<CardNo/>
<CardExpiry/>
<CardholderName/>
<AcquirerName>ASB</AcquirerName>
<AcquirerMerchantID/>
<PaystationUserID/>
<PaystationTransactionID>0085710398-01</PaystationTransactionID>
<MerchantSession>4653ca3f-7967-4ac5-8661-1e034e2478a4</MerchantSession>
<TransactionTime>2017-01-11 14:48:19</TransactionTime>
<PurchaseAmount>5000</PurchaseAmount>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcquirerResponseCode/>
<QSIResponseCode/>
<PaystationErrorCode/>
<BatchNumber/>
<CardType/>
<AuthorizeID/>
<POPPErrorCode/>
<POPPErrorMessage/>
<TransactionProcess>purchase</TransactionProcess>
<RefundAmount/>
<PaystationErrorMessageExtended/>
<FuturePaymentToken/>
<SurchargeAmount/>
<TotalSuccessfulRefunds>0</TotalSuccessfulRefunds>
<TotalSuccessfulCaptures>0</TotalSuccessfulCaptures>
<PaystationErrorMessage>Incomplete</PaystationErrorMessage>
<Authentication>
<auth_Type/>
<auth_Status/>
<auth_SecurityLevel/>
<auth_HashToken/>
<auth_3DSID/>
<auth_3DSElectronicCommerceIndicator/>
<auth_3DSEnrolled/>
<auth_3DSStatus/>
</Authentication>
<HostedTransactionFlow>
<RemoteServerInitiationRequest>2017-01-11 14:48:19</RemoteServerInitiationRequest>
<PaystationInitiationResponse>2017-01-11 14:48:19</PaystationInitiationResponse>
<BrowserRequestedCardSelectionScreen/>
<PaystationReturnedCardSelectionScreen/>
<BrowserRequestedCardDetailsScreen/>
<PaysationReturnedCardDetailsScreen/>
<BrowserSubmittedCardDetails/>
<ThreeDSMPIRequestInitiated/>
<ThreeDSMPIResponseReceived/>
<PaystationPaymentThreadStarted/>
<PaystationPaymentInitiationConfirmation/>
<PaystationLinkedGatewayMessageSent/>
<AcquirerLinkResponseReceived/>
<ThreeDSAuthenticationRequestSent/>
<ThreeDSAuthenticationResponseReceived/>
<PaystationPOSTResponseCompleted/>
<BrowserPaymentStatusCheck/>
<PaystationPaymentStatusResponse/>
<PaystationTransactionCompletedResponse/>
</HostedTransactionFlow>
</LookupResponse>
</PaystationQuickLookup>
The above command returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<PaystationQuickLookup>
<LookupStatus>
<LookupCode>03</LookupCode>
<LookupMessage>Access denied for user [123456]</LookupMessage>
<RemoteHostAddress>123.123.123.12</RemoteHostAddress>
</LookupStatus>
</PaystationQuickLookup>
Quick lookup queries are initiated via an HTTP GET query to a Paystation Lookup URL. The response is sent directly back as an XML formatted response. This response includes the relevant parameters sent through to Paystation from the cart transaction, financial transaction and authentication data from the bank's Internet gateway stored at the time of the purchase transaction. The lookup can be referenced by either a previously used merchant session (ms)
value, and/or from the transaction identitfier (ti)
.
HTTP request
GET https://payments.paystation.co.nz/lookup/
Required POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pi | Paystation ID | The Paystation ID | String value | 612345 |
Required choice query parameters
With Quick lookup you have two options available in terms of identifying a transaction - the merchant session (ms)
, or the transaction id (ti)
. The API will accept either of these two parameters to identify a transaction, or alternatively you can use both.
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
ms | Merchant Session ID | The unique identification code sent to Paystation as the pstn_ms value in the original payment request |
String value (max 64 chars) | qwertyuiop1234567890 |
ti | Transaction ID | The original transaction ID that Paystation has assigned to the transaction | String value | 0084873084-01 |
HTTP response
The response is sent in the form of an XML packet. You will be able to extract the response values using the standard tools available within your development environment
Parameter | Name | Description | Example |
---|---|---|---|
AcquirerName | Merchants Acquirer Name | The merchants acquirer name | string |
AcquirerMerchantID | Acquirer Merchant ID | The acquirer’s merchant ID used for the transaction | integer |
PaystationUserID | Paystation username | Paystation user name used to create transaction | string |
PaystationTransactionID | Transaction ID | A string containing the unique transaction ID assigned to the transaction attempt by the Paystation server | string |
PurchaseAmount | Purchase Amount | The amount of the transaction, in cents | 4200 |
MerchantSession | Merchant Session | A string containing the unique reference assigned to the transaction by the merchants system | string |
ReturnReceiptNumber | Return Receipt Number | The RRN number is a virtual terminal counter for the transaction and is not unique | Integer |
ShoppingTransactionNumber | Shopping Transaction Number | Unique bank reference assigned to the transaction | Integer |
AcquirerResponseCode | Acquirer’s response code | The result code’s vary from acquirer to acquirer and is included for debugging purposes. Please process transaction result from the PaystationErrorCode | Integer |
QSIResponseCode | QSI Response Code | Payment Server Response code – the actual raw result from the payment server. Please process transaction result from the PaystationErrorCode | Integer |
PaystationErrorCode | Paystation Error Code | The result of the transaction | integer |
BatchNumber | Batch Number | The Batch number on the Payment Server that this transaction will be added to in order to be processed by the acquiring institution | date MMDD |
Cardtype | Card type | The card type used | MASTERCARD |
Errors
A Quick Lookup response XML packet is broken down into two separate xml element groups, the LookupStatus
and the LookupResponse
LookupStatus errors
The LookupStatus
holds the data depending on wherever the actual request for the Lookup was successful
Through the LookupCode
and LookupMessage
xml elements of a LookupStatus
you will obtain an error code that corresponds to the below link
The LookupStatus
error's are all standard lookup errors found here
LookupResponse errors
The LookupResponse
holds the data depending on the outcome of the transaction found.
The LookupResponse
error's are all standard transaction errors found here
Refund
Using our Refund API you can process a refund remotely using an API call.
Refund transaction
Refund a transaction directly using the corresponding transaction ID
2 party
Example Request
POST https://www.paystation.co.nz/direct/paystation.dll
POST body parameters
paystation=_empty
&pstn_nr=t
&pstn_pi=123456
&pstn_gi=PAYSTATION
&pstn_ms=abcd-defg-hijk
&pstn_am=5000
&pstn_2p=t
&pstn_rc=t
&pstn_rt=00123456789-01
This endpoint is used for refunding a transaction. This is a 2 party transaction.
HTTP request
POST https://www.paystation.co.nz/direct/paystation.dll
Required POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
paystation | Transaction initiator flag | Required for payment engine | String value | _empty |
pstn_nr | No Redirect flag | Required for payment engine | Single character "t" or "T" | T |
pstn_pi | Paystation ID | The Paystation ID | String value | 612345 |
pstn_gi | Gateway ID | The Gateway ID | String value | PAYSTATION |
pstn_ms | Merchant Session ID | A unique identifier for every transaction attempt | String value (max 64 chars) | qwertyuiop1234567890 |
pstn_am | Amount | Transaction amount | Integer only, default format is cents | 4200 |
pstn_2p | Two party flag | Required for 2-party transactions | Single character "t" or "T" | T |
pstn_rc | Refund flag | Required for refund transactions | Single character "t" or "T" | T |
pstn_rt | Refund transaction ID | The transaction ID to be refunded | String value | 0066758901-01 |
Optional POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_tm | Test mode | Used to create a transaction in test mode | Single character "t" or "T" | T |
pstn_mr | Merchant reference | A non-unique identifier that can be assigned to a transaction | String value (max 64 chars) | abc123 |
pstn_mc | Customer details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_mo | Order details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_rf | Return format | Defines the response format from Paystation (default is XML) | String value | JSON |
Optional query string parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_HMACTimestamp | HMAC Timestamp | The timestamp generated immediately before the request is generated | integer | 1481496738 |
pstn_HMAC | HMAC Hash | A hash of the request, the HMAC timestamp and the HMAC key | string | abc12345 |
Return response
The above request returns on SUCCESS an XML response structured like this:
<?xml version="1.0" standalone="yes"?>
<PaystationRefundResponse>
<ec>0</ec>
<em>Transaction successful</em>
<ti>0085793423-01</ti>
<ct>mastercard</ct>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085793423-01</TransactionID>
<RefundAmount>5000</RefundAmount>
<SurchargeAmount/>
<Locale>en</Locale>
<ReturnReceiptNumber>85793423</ReturnReceiptNumber>
<ShoppingTransactionNumber/>
<AcqResponseCode>00</AcqResponseCode>
<QSIResponseCode>0</QSIResponseCode>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-13 11:09:03</TransactionTime>
<PaystationErrorCode>0</PaystationErrorCode>
<PaystationErrorMessage>Transaction successful</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<CardNo>555555XXXXXXX444</CardNo>
<CardExpiry>1705</CardExpiry>
<TransactionProcess>refund</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber>0113</BatchNumber>
<AuthorizeID/>
<Cardtype>MC</Cardtype>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-13 11:09:03</PaymentRequestTime>
<DigitalOrderTime>2017-01-13 11:09:03</DigitalOrderTime>
<DigitalReceiptTime/>
<PaystationTransactionID/>
<RefundedAmount>5000</RefundedAmount>
<CapturedAmount/>
</PaystationRefundResponse>
The above request returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<PaystationRefundResponse>
<ec>14</ec>
<em>Transaction could not be found</em>
<ti>0085793478-01</ti>
<ct/>
<merchant_ref/>
<tm>P</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085793478-01</TransactionID>
<RefundAmount>5000</RefundAmount>
<SurchargeAmount/>
<Locale>en</Locale>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-13 11:10:06</TransactionTime>
<PaystationErrorCode>14</PaystationErrorCode>
<PaystationErrorMessage>Transaction could not be found</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>refund</TransactionProcess>
<TransactionMode>P</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype/>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-13 11:10:06</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime/>
<PaystationTransactionID/>
</PaystationRefundResponse>
Attribute | Name | Description | Type | Example |
---|---|---|---|---|
ec | Error code | The error code status of the transaction | integer | 1 |
em | Error message | The error message status of the transaction | string | Transaction successful |
ti | Transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
ct | Card type | The card issuer | string | mastercard |
merchant_ref | A non-unique identifier that can be assigned to a transaction | string | abc123 | |
tm | Test mode | Denotes if the transaction was completed in test mode or not | string | t |
MerchantSession | Merchant Session ID | A unique value to identify a transaction by | string | abcd-defg-hijk |
UsedAcquirerMerchantID | ||||
TransactionID | Transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
PurchaseAmount | Purchase amount | A positive integer in cent value or alternatively the option specified in the transaction representing the charged amount | positive integer or zero | 5000 |
SurchargeAmount | Surcharge amount added to transaction amount | Integer only | default format is cents | 4200 |
Locale | Locale | The language tag represents the language the response text is provided in | string value | en |
ReturnReceiptNumber | Return receipt number | The RRN number is a virtual terminal counter for the transaction and is not unique | positive 8 digit number | 85789579 |
ShoppingTransactionNumber | Shopping transaction number | Is a unique number relating to the Transaction ID (eGate integration's only) | Integer | 85793423 |
AcqResponseCode | Acq response code | Transaction response code from the acquiring bank | Integer | 00 |
QSIResponseCode | QSI response code | Issuing bank response code – the actual raw result from the payment server. Please process transaction result from the PaystationErrorCode | Integer | 0 |
CSCResultCode | CSC result code | The response code in response to verifying the card security code if applicable to transaction | Single character | "M" |
AVSResultCode | AVS result code | Result of any AVS validation. Not supported in New Zealand | Empty | |
TransactionTime | Transaction time | The time the transaction was completed | datetime | 2017-01-13 09:38:26 |
PaystationErrorCode | Error code | The error code status of the transaction | integer | 1 |
PaystationErrorMessage | Error message | The error message status of the transaction | string | Transaction successful |
PaystationExtendedErrorMessage | Extended error message | Extra information regarding the error code if applicable | string value | Refer to card issuer |
MerchantReference | Merchant reference | A non-unique identifier that can be assigned to a transaction | string | abc123 |
CardNo | Card number | A masked card number of the card that completed the transaction | string | 555555XXXXXXX444 |
CardExpiry | Card expiry date | The expiry of the card that completed the transaction | date YYMM | 1705 |
TransactionProcess | Transaction process | The transaction method identification | string | refund |
TransactionMode | Transaction mode | T or P represents the transaction is a test (T) or production (P) transaction | string value | T |
BatchNumber | Batch number | A four digit number representing the expected settlement date of the transaction in the format MMDD | positive integer | 0013 |
AuthorizeID | Authorize ID | A unique reference provided by the bank to trace the transaction | integer | R81194 |
Cardtype | Card type | The card issuer | string | MC |
Username | Paystation account ID | The Paystation account ID that initiated the transaction | integer | 123456 |
RequestIP | Request ip | The ip used in the initiation of the request | string | 192.168.1.1 |
RequestUserAgent | Request user agent | String that identifies the application client that initiated the transaction request | string | Mozilla/5.0 |
RequestHttpReferrer | Request http referrer | HTTP referrer header if applicable to original transaction request | string value | https://www.example.com |
PaymentRequestTime | Payment request time | The time the transaction was initiated at | datetime | 2017-01-13 09:38:26 |
DigitalOrderTime | Digital order time | Timestamp the transaction URL was created (does not apply to 2-party transactions) | datetime | 2018-03-11 02:40:16 |
DigitalReceiptTime | Digital receipt time | Timestamp the transaction response was received by the card switch | datetime | 2018-03-11 02:40:16 |
PaystationTransactionID | Paystation transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
RefundAmount | Refunded amount | The amount refunded in the transaction | positive integer | 5000 |
CapturedAmount | Captured amount | The amount captured in the transaction (does not apply to a refund request) | positive integer | 1000 |
Auth and Capture
Using authorisations and captures means that you use an authorisation to verify that the card details are correct, and it sets money aside on the card balance. The benefit here is that you can guarantee an amount and then finalize payment once the details have been confirmed.
What it is: The customer gives you authority to take up to a set amount from their credit card.
How it works: You capture some or the entire authorised amount. When the customer is giving authority, your website tells Paystation the amount to authorise. The customer enters their credit card details into the payment page and the details go directly to the bank. When you are ready you are able to capture up to that amount in single or multiple captures.
Benefit: A credit or debit card can be validated for the purposes of future transactions against that card.
Downside: An authorisation is active for a set period of time and is controlled by the acquiring bank (the bank providing the merchant facility). If the authorisation is left for too long prior to capture, the credit card may have expired, or the balance will have changed, between the time when the authorisation is given and the amount is captured.
Who uses authorisation / capture (sometimes referred to as a pre-auth): Accommodation services, and food delivery services are the most common, but any business that needs to confirm an order availability, or with goods and services subject to change can benefit from using pre authorised payments.
Authorisation
An authorisation confirms that the card number and expiry date are correct. It also sets aside a specific amount of money on that card, which means that the cardholder cannot access those funds until the authorisation has been released, or the funds captured.
2 party
Example request
POST https://www.paystation.co.nz/direct/paystation.dll
POST body parameters
paystation=_empty
&pstn_nr=t
&pstn_pi=123456
&pstn_gi=PAYSTATION
&pstn_ms=abcd-defg-hijk
&pstn_am=5000
&pstn_2p=t
&pstn_cn=5555555555554444
&pstn_ex=1705
&pstn_pa=t
This endpoint is used to initiate a 2 party transaction
HTTP request
POST https://www.paystation.co.nz/direct/paystation.dll
Required POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
paystation | Transaction initiator flag | Required for payment engine | String value | _empty |
pstn_nr | No Redirect flag | Required for payment engine | Single character "t" or "T" | T |
pstn_pi | Paystation ID | The Paystation ID | String value | 612345 |
pstn_gi | Gateway ID | The Gateway ID | String value | PAYSTATION |
pstn_ms | Merchant Session ID | A unique identifier for every transaction attempt | String value (max 64 chars) | qwertyuiop1234567890 |
pstn_am | Amount | Transaction amount | Integer only, default format is cents | 4200 |
pstn_2p | Two party flag | Required for 2-party transactions | Single character "t" or "T" | T |
pstn_cn | Card number | Credit/debit card number (13 - 19 characters) | Integer, no spaces in between card numbers | 5555555555554444 |
pstn_ex | Card expiry date | Four character expiry date | Integer, no spaces in between year and month (default is yymm format) | 1705 |
pstn_pa | Authorisation flag | Required for authorisation transactions | Single character "t" or "T" | T |
Optional POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_cu | Currency | Currency the transaction will be created in | String value | USD |
pstn_tm | Test mode | Used to create a transaction in test mode | Single character "t" or "T" | T |
pstn_mr | Merchant reference | A non-unique identifier that can be assigned to a transaction | String value (max 64 chars) | abc123 |
pstn_ct | Card type | Stating the card type can bypass the card selection screen of a 3-party transaction | String value (max 64 chars) | visa |
pstn_df | Card expiry date format | Defines the format of the expiry date | "mmyy" or "yymm" | mmyy |
pstn_af | Amount format | Defines the format of the amount | String value "dollars.cents" or "cents" | dollars.cents |
pstn_mc | Customer details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_mo | Order details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_cc | Card security code | Three/Four digit code found on back of credit/debit card | String value | 100 |
pstn_rf | Return format | Defines the response format from Paystation (default is XML) | String value | JSON |
Optional query string parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_HMACTimestamp | HMAC Timestamp | The timestamp generated immediately before the request is generated | integer | 1481496738 |
pstn_HMAC | HMAC Hash | A hash of the request, the HMAC timestamp and the HMAC key | string | abc12345 |
Return response
The above command returns on SUCCESS an XML response structured like this:
<?xml version="1.0" standalone="yes"?>
<response>
<ec>0</ec>
<em>Transaction successful</em>
<ti>0085898476-01</ti>
<ct>mastercard</ct>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085898476-01</TransactionID>
<PurchaseAmount>5000</PurchaseAmount>
<SurchargeAmount/>
<Locale/>
<ReturnReceiptNumber>85898476</ReturnReceiptNumber>
<ShoppingTransactionNumber/>
<AcqResponseCode>00</AcqResponseCode>
<QSIResponseCode>0</QSIResponseCode>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 09:09:22</TransactionTime>
<PaystationErrorCode>0</PaystationErrorCode>
<PaystationErrorMessage>Transaction successful</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<CardNo>555555XXXXXXX444</CardNo>
<CardExpiry>1705</CardExpiry>
<TransactionProcess>authorisation</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber>0116</BatchNumber>
<AuthorizeID/>
<Cardtype>MC</Cardtype>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 09:09:22</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime>2017-01-16 09:09:22</DigitalReceiptTime>
<PaystationTransactionID>0085898476-01</PaystationTransactionID>
<IssuerName>unknown</IssuerName>
<IssuerCountry>unknown</IssuerCountry>
</response>
The above command returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<PaystationAuthorisationResponse>
<ec>41</ec>
<em>Card number has failed Luhn check</em>
<ti>0085898619-01</ti>
<ct/>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085898619-01</TransactionID>
<AuthoriseAmount>5000</AuthoriseAmount>
<SurchargeAmount/>
<Locale>en</Locale>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 09:12:05</TransactionTime>
<PaystationErrorCode>41</PaystationErrorCode>
<PaystationErrorMessage>Card number has failed Luhn check</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>purchase</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype/>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 09:12:05</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime/>
<PaystationTransactionID/>
<IssuerName>unknown</IssuerName>
<IssuerCountry>unknown</IssuerCountry>
</PaystationAuthorisationResponse>
Attribute | Name | Description | Type | Example |
---|---|---|---|---|
ec | Error code | The error code status of the transaction | integer | 1 |
em | Error message | The error message status of the transaction | string | Transaction successful |
ti | Transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
ct | Card type | The card issuer | string | mastercard |
merchant_ref | A non-unique identifier that can be assigned to a transaction | string | abc123 | |
tm | Test mode | Denotes if the transaction was completed in test mode or not | string | t |
MerchantSession | Merchant Session ID | A unique value to identify a transaction by | string | abcd-defg-hijk |
UsedAcquirerMerchantID | ||||
TransactionID | Transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
PurchaseAmount | Purchase amount | A positive integer in cent value or alternatively the option specified in the transaction representing the charged amount | positive integer or zero | 5000 |
SurchargeAmount | ||||
Locale | Locale | The language tag represents the language the response text is provided in | string value | en |
ReturnReceiptNumber | Return receipt number | The RRN number is a virtual terminal counter for the transaction and is not unique | Integer | 85789579 |
ShoppingTransactionNumber | Shopping transaction number | Is a unique number relating to the Transaction ID (eGate integration's only) | Integer | 85793423 |
AcqResponseCode | Acq response code | Transaction response code from the acquiring bank | Integer | 00 |
QSIResponseCode | QSI response code | Issuing bank response code – the actual raw result from the payment server. Please process transaction result from the PaystationErrorCode | Integer | 0 |
CSCResultCode | CSC result code | The response code in response to verifying the card security code if applicable to transaction | Single character | "M" |
AVSResultCode | AVS result code | Result of any AVS validation. Not supported in New Zealand | Empty | |
TransactionTime | Transaction time | The time the transaction was completed | datetime | 2017-01-13 09:38:26 |
PaystationErrorCode | Error code | The error code status of the transaction | integer | 1 |
PaystationErrorMessage | Error message | The error message status of the transaction | string | Transaction successful |
PaystationExtendedErrorMessage | Extended error message | Extra information regarding the error code if applicable | string value | Refer to card issuer |
MerchantReference | Merchant reference | A non-unique identifier that can be assigned to a transaction | string | abc123 |
CardNo | Card number | A masked card number of the card that completed the transaction | string | 555555XXXXXXX444 |
CardExpiry | Card expiry date | The expiry of the card that completed the transaction | date YYMM | 1705 |
TransactionProcess | Transaction process | The transaction method identification | string | purchase |
TransactionMode | Transaction mode | T or P represents the transaction is a test (T) or production (P) transaction | string value | T |
BatchNumber | Batch number | A four digit number representing the expected settlement date of the transaction in the format MMDD | positive integer | 0013 |
AuthorizeID | Authorize ID | A unique reference provided by the bank to trace the transaction | string value | R81194 |
Cardtype | Card type | The card issuer | string | MC |
Username | Paystation account ID | The Paystation account ID that initiated the transaction | integer | 123456 |
RequestIP | Request ip | The ip used in the initiation of the request | string | 192.168.1.1 |
RequestUserAgent | Request user agent | String that identifies the application client that initiated the transaction request | string | Mozilla/5.0 |
RequestHttpReferrer | Request http referrer | HTTP referrer header if applicable to original transaction request | string value | https://www.example.com |
PaymentRequestTime | Payment request time | The time the transaction was initiated at | datetime | 2017-01-13 09:38:26 |
DigitalOrderTime | Digital order time | Timestamp the transaction URL was created (does not apply to 2-party transactions) | datetime | 2018-03-11 02:40:16 |
DigitalReceiptTime | Digital receipt time | Timestamp the transaction response was received by the card switch | dateime | 2018-03-11 02:40:16 |
PaystationTransactionID | Paystation transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
IssuerName | Issuer name | The card issuing institution if known | string value | KIWIBANK LIMITED |
IssuerCountry | Issuer country | The country the card was issued if known | string value | NEW ZEALAND |
3 party
Example request
POST https://www.paystation.co.nz/direct/paystation.dll
POST body parameters
paystation=_empty
&pstn_nr=t
&pstn_pi=123456
&pstn_gi=PAYSTATION
&pstn_ms=abcd-defg-hijk
&pstn_am=5000
&pstn_2p=t
&pstn_cn=5555555555554444
&pstn_ex=1705
&pstn_pa=t
HTTP request
POST https://www.paystation.co.nz/direct/paystation.dll
Required POST body parameters
Parameter | Name | Description | Example |
---|---|---|---|
paystation | Transaction initiator flag | Required for payment engine | String value |
pstn_nr | No Redirect flag | Required for payment engine | Single character "t" or "T" |
pstn_pi | Paystation ID | The Paystation ID | String value |
pstn_gi | Gateway ID | The Gateway ID | String value |
pstn_ms | Merchant Session ID | A unique identifier for every transaction attempt | String value (max 64 chars) |
pstn_am | Amount | Transaction amount | Integer only, default format is cents |
pstn_pa | Authorisation flag | Required for authorisation transactions | Single character "t" or "T" |
Optional POST body parameters
Parameter | Name | Description | Example |
---|---|---|---|
pstn_cu | Currency | Currency the transaction will be created in | String value |
pstn_tm | Test mode | Used to create a transaction in test mode | Single character "t" or "T" |
pstn_mr | Merchant reference | A non-unique identifier that can be assigned to a transaction | String value (max 64 chars) |
pstn_ct | Card type | Stating the card type can bypass the card selection screen of a 3-party transaction | String value (max 64 chars) |
pstn_df | Card expiry date format | Defines the format of the expiry date | "mmyy" or "yymm" |
pstn_af | Amount format | Defines the format of the amount | String value "dollars.cents" or "cents" |
pstn_mc | Customer details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) |
pstn_mo | Order details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) |
pstn_du | Dynamic Return URL | The URL to re-direct the customer to after a 3-party transaction | URL encoded string value |
pstn_dp | Dynamic POST Response URL | The URL to send the POST Response to after a 3-party transaction | URL encoded string value |
pstn_rf | Return format | Defines the response format from Paystation (default is XML) | String value |
HTTP response
The above command returns on SUCCESS an XML response structured like this:
<?xml version="1.0" standalone="yes"?>
<InitiationRequestResponse>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 09:14:37</PaymentRequestTime>
<DigitalOrder>https://payments.paystation.co.nz/hosted/?hk=AxJBC_HnpLdKXhe1i</DigitalOrder>
<DigitalOrderTime>2017-01-16 09:14:37</DigitalOrderTime>
<DigitalReceiptTime/>
<PaystationTransactionID>0085898734-01</PaystationTransactionID>
</InitiationRequestResponse>
The above command returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<PaystationAuthorisationResponse>
<ec>13</ec>
<em>Transaction already in progress</em>
<ti>0085898790-01</ti>
<ct/>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085898790-01</TransactionID>
<AuthoriseAmount>5000</AuthoriseAmount>
<SurchargeAmount/>
<Locale>en</Locale>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 09:16:15</TransactionTime>
<PaystationErrorCode>13</PaystationErrorCode>
<PaystationErrorMessage>Transaction already in progress</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>purchase</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype/>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 09:16:15</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime/>
<PaystationTransactionID/>
</PaystationAuthorisationResponse>
Attribute | Name | Description | Type | Example |
---|---|---|---|---|
Username | Paystation account ID | The Paystation account ID that initiated the transaction | integer | 123456 |
RequestIP | Request ip | The ip used in the initiation of the request | string | 192.168.1.1 |
RequestUserAgent | Request user agent | String that identifies the application client that initiated the transaction request | string | Mozilla/5.0 |
RequestHttpReferrer | Request http referrer | HTTP referrer header if applicable to original transaction request | string value | https://www.example.com |
PaymentRequestTime | Payment request time | The time the transaction was initiated at | datetime | 2017-01-13 09:38:26 |
DigitalOrder | Digital order URL | The hosted payment page URL link for the transaction | URL | https://payments.paystation.co.nz/hosted/?hk=12345 |
DigitalOrderTime | Digital order time | Timestamp the transaction URL was created (does not apply to 2-party transactions) | datetime | 2018-03-11 -2:40:16 |
DigitalReceiptTime | Digital receipt time | Timestamp the transaction response was received by the card switch | datetime | 2018-03-11 02:40:16 |
PaystationTransactionID | Paystation transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
Capture
A capture is the second part to an authorisation. Once the funds on a card have been authorised successfully, you will be able to perform a capture accept payment.
2 party
Example Request
POST https://www.paystation.co.nz/direct/paystation.dll
POST body parameters
paystation=_empty
&pstn_nr=t
&pstn_pi=123456
&pstn_gi=PAYSTATION
&pstn_ms=abcd-defg-hijk
&pstn_am=5000
&pstn_2p=t
&pstn_cn=5555555555554444
&pstn_ex=1705
&pstn_cp=t
HTTP request
POST https://www.paystation.co.nz/direct/paystation.dll
Required POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
paystation | Transaction initiator flag | Required for payment engine | String value | _empty |
pstn_nr | No Redirect flag | Required for payment engine | Single character "t" or "T" | T |
pstn_pi | Paystation ID | The Paystation ID | String value | 612345 |
pstn_gi | Gateway ID | The Gateway ID | String value | PAYSTATION |
pstn_ms | Merchant Session ID | A unique identifier for every transaction attempt | String value (max 64 chars) | qwertyuiop1234567890 |
pstn_am | Amount | Transaction amount | Integer only, default format is cents | 4200 |
pstn_2p | Two party flag | Required for 2-party transactions | Single character "t" or "T" | T |
pstn_cp | Capture flag | Required for capture transactions | Single character "t" or "T" | T |
pstn_cx | Capture transaction ID | The transaction ID to be captured | String value | 0012345678-01 |
Optional POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_tm | Test mode | Used to create a transaction in test mode | Single character "t" or "T" | T |
pstn_mr | Merchant reference | A non-unique identifier that can be assigned to a transaction | String value (max 64 chars) | abc123 |
pstn_ct | Card type | Stating the card type can bypass the card selection screen of a 3-party transaction | String value (max 64 chars) | visa |
pstn_df | Card expiry date format | Defines the format of the expiry date | "mmyy" or "yymm" | mmyy |
pstn_af | Amount format | Defines the format of the amount | String value "dollars.cents" or "cents" | dollars.cents |
pstn_mc | Customer details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_mo | Order details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_rf | Return format | Defines the response format from Paystation (default is XML) | String value | JSON |
Optional query string parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_HMACTimestamp | HMAC Timestamp | The timestamp generated immediately before the request is generated | integer | 1481496738 |
pstn_HMAC | HMAC Hash | A hash of the request, the HMAC timestamp and the HMAC key | string | abc12345 |
Return response
The above command returns on SUCCESS an XML response structured like this:
<?xml version="1.0" standalone="yes"?>
<PaystationCaptureResponse>
<ec>0</ec>
<em>Transaction successful</em>
<ti>0085898954-01</ti>
<ct>mastercard</ct>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085898954-01</TransactionID>
<CaptureAmount>5000</CaptureAmount>
<SurchargeAmount/>
<Locale/>
<ReturnReceiptNumber>85898954</ReturnReceiptNumber>
<ShoppingTransactionNumber/>
<AcqResponseCode>00</AcqResponseCode>
<QSIResponseCode>0</QSIResponseCode>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 09:20:19</TransactionTime>
<PaystationErrorCode>0</PaystationErrorCode>
<PaystationErrorMessage>Transaction successful</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<CardNo>555555XXXXXXX444</CardNo>
<CardExpiry>1705</CardExpiry>
<TransactionProcess>capture</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber>0116</BatchNumber>
<AuthorizeID/>
<Cardtype>MC</Cardtype>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 09:20:19</PaymentRequestTime>
<DigitalOrderTime>2017-01-16 09:20:19</DigitalOrderTime>
<DigitalReceiptTime>2017-01-16 09:20:19</DigitalReceiptTime>
<PaystationTransactionID/>
<RefundedAmount/>
<CapturedAmount>5000</CapturedAmount>
<AuthorisedAmount/>
</PaystationCaptureResponse>
The above command returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<PaystationCaptureResponse>
<ec>14</ec>
<em>Transaction could not be found</em>
<ti>0085899005-01</ti>
<ct/>
<merchant_ref/>
<tm>P</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085899005-01</TransactionID>
<CaptureAmount>5000</CaptureAmount>
<SurchargeAmount/>
<Locale/>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 09:21:13</TransactionTime>
<PaystationErrorCode>14</PaystationErrorCode>
<PaystationErrorMessage>Transaction could not be found</PaystationErrorMessage>
<PaystationExtendedErrorMessage>Transaction could not be found</PaystationExtendedErrorMessage>
<MerchantReference/>
<TransactionProcess>capture</TransactionProcess>
<TransactionMode>P</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype/>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 09:21:13</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime>2017-01-16 09:21:13</DigitalReceiptTime>
<PaystationTransactionID/>
</PaystationCaptureResponse>
Attribute | Name | Description | Type | Example |
---|---|---|---|---|
ec | Error code | The error code status of the transaction | integer | 1 |
em | Error message | The error message status of the transaction | string | Transaction successful |
ti | Transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
ct | Card type | The card issuer | string | mastercard |
merchant_ref | A non-unique identifier that can be assigned to a transaction | string | abc123 | |
tm | Test mode | Denotes if the transaction was completed in test mode or not | string | t |
MerchantSession | Merchant Session ID | A unique value to identify a transaction by | string | abcd-defg-hijk |
UsedAcquirerMerchantID | ||||
TransactionID | Transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
CaptureAmount | Capture amount | A positive integer in cent value or alternatively the option specified in the transaction representing the captured amount | positive integer or zero | 5000 |
SurchargeAmount | Surcharge amount | Surcharge amount added to transaction amount | Integer only, default format is cents | 4200 |
Locale | Locale | The language tag represents the language the response text is provided in | string value | en |
ReturnReceiptNumber | Return receipt number | The RRN number is a virtual terminal counter for the transaction and is not unique | Integer | 85793423 |
ShoppingTransactionNumber | Shopping transaction number | Is a unique number relating to the Transaction ID (eGate integration's only) | Integer | 85793423 |
AcqResponseCode | Acq response code | Transaction response code from the acquiring bank | Integer | 00 |
QSIResponseCode | QSI response code | Transaction response code from the issuing bank | Integer | 0 |
CSCResultCode | CSC result code | The response code in response to verifying the card security code if applicable to transaction | Single character | "M" |
AVSResultCode | AVS result code | Result of any AVS validation. Not supported in New Zealand | ||
TransactionTime | Transaction time | The time the transaction was completed | datetime | 2017-01-13 09:38:26 |
PaystationErrorCode | Error code | The error code status of the transaction | integer | 1 |
PaystationErrorMessage | Error message | The error message status of the transaction | string | Transaction successful |
PaystationExtendedErrorMessage | Extended error message | Extra information regarding the error code if applicable | string value | Refer to card issuer |
MerchantReference | Merchant reference | A non-unique identifier that can be assigned to a transaction | string | abc123 |
CardNo | Card number | A masked card number of the card that completed the transaction | string | 555555XXXXXXX444 |
CardExpiry | Card expiry date | The expiry of the card that completed the transaction | date YYMM | 1705 |
TransactionProcess | Transaction process | The transaction method identification | string | refund |
TransactionMode | Transaction mode | T or P represents the transaction is a test (T) or production (P) transaction | string value | T |
BatchNumber | Batch number | A four digit number representing the expected settlement date of the transaction in the format MMDD | positive integer | 0518 |
AuthorizeID | Authorize ID | A unique reference provided by the bank to trace the transaction | string value | R81194 |
Cardtype | Card type | The card issuer | string | MC |
Username | Paystation account ID | The Paystation account ID that initiated the transaction | integer | 123456 |
RequestIP | Request ip | The ip used in the initiation of the request | string | 192.168.1.1 |
RequestUserAgent | Request user agent | String that identifies the application client that initiated the transaction request | string | Mozilla/5.0 |
RequestHttpReferrer | Request http referrer | HTTP referrer header if applicable to original transaction request | string value | https://www.example.com |
PaymentRequestTime | Payment request time | The time the transaction was initiated at | datetime | 2017-01-13 09:38:26 |
DigitalOrderTime | Digital order time | Timestamp the transaction URL was created (does not apply to 2-party transactions) | datetime | 2018-03-11 02:40:16 |
DigitalReceiptTime | Digital receipt time | Timestamp the transaction response was received by the card switch | datetime | 2018-03-11 02:40:16 |
PaystationTransactionID | Paystation transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
RefundAmount | Refunded amount | The amount refunded in the transaction (does not apply to a capture transaction) | positive integer | 5000 |
CapturedAmount | Captured amount | The amount captured in the transaction | positive integer | 1000 |
AuthorisedAmount | Authorised amount | The amount authorised to be captured in the transaction | positive integer | 1000 |
Token payments
Tokens provide a safe and simple way to save and credit card details securely in our card vault.
What it is: The customer gives you the authority to take money from their credit card whenever you want.
How it works: The customer enters the credit card into your site. Your website sends Paystation the credit card number and we return a token. You discard the credit card number (but you might store the first 6 and last 4 digits and the expiry date so that you can let people see what card you are about to debit each time. You can then use the token to debit the card number whenever you need to - you give us back the token and we put the payment through against the card.
Benefit: You are able to take more than one payment from the same credit card in this situation, and can set up your own recurring or automated payments if that is what you require.
Downside: When the credit card expires the token is no longer any use and you will need to go back to the cardholder to get a new credit card number and expiry date. You will need to have 2 party processing enabled your account to complete a token payments integration.
Who uses tokenisation?: - Power companies, charities, and any business where the customer has an account that needs to be credited more than once by credit card.
Token save
With a token save the supplied card details are stored and encrypted in our card vault, you can then use that cards token for future payments by sending Paystation a token bill transaction request.
2 party
This endpoint is used for saving a token, this is a 2 party transaction only
Example request
POST https://www.paystation.co.nz/direct/paystation.dll
POST body parameters
paystation=_empty
&pstn_nr=t
&pstn_pi=123456
&pstn_gi=PAYSTATION
&pstn_ms=abcd-defg-hijk
&pstn_2p=t
&pstn_fp=t
&pstn_fs=t
&pstn_cn=5555555555554444
&pstn_ex=1705
HTTP request
POST https://www.paystation.co.nz/direct/paystation.dll
Required POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
paystation | Transaction initiator flag | Required for payment engine | String value | _empty |
pstn_nr | No Redirect flag | Required for payment engine | Single character "t" or "T" | T |
pstn_pi | Paystation ID | The Paystation ID | String value | 612345 |
pstn_gi | Gateway ID | The Gateway ID | String value | PAYSTATION |
pstn_ms | Merchant Session ID | A unique identifier for every transaction attempt | String value (max 64 chars) | qwertyuiop1234567890 |
pstn_2p | Two party flag | Required for 2-party transactions | Single character "t" or "T" | T |
pstn_fp | Token transaction flag | Required for all token transactions (except independent token refunds) | Single character "t" or "T" | T |
pstn_fs | Token save only flag | Required for token save only transactions | Single character "t" or "T" | T |
pstn_cn | Card number | Credit/debit card number (13 - 19 characters) | Integer, no spaces in between card numbers | 5555555555554444 |
pstn_ex | Card expiry date | Four character expiry date | Integer, no spaces in between year and month (default is yymm format) | 1705 |
Optional POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_am | Amount | Transaction amount | Integer only, default format is cents | 4200 |
pstn_cu | Currency | Currency the transaction will be created in | String value | USD |
pstn_mr | Merchant reference | A non-unique identifier that can be assigned to a transaction | String value (max 64 chars) | abc123 |
pstn_ct | Card type | Stating the card type can bypass the card selection screen of a 3-party transaction | String value (max 64 chars) | visa |
pstn_df | Card expiry date format | Defines the format of the expiry date | "mmyy" or "yymm" | mmyy |
pstn_af | Amount format | Defines the format of the amount | String value "dollars.cents" or "cents" | dollars.cents |
pstn_mc | Customer details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_mo | Order details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_ft | Token name | A unique identifier that credit card details have been stored against previously | String value (max 64 chars) | qwertyuiop1234567890 |
pstn_fr | Reseller flag | Allows an account to make a transaction using the token from another account | Single character "t" or "T" | T |
pstn_rf | Return format | Defines the response format from Paystation (default is XML) | String value | JSON |
Optional query string parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_HMACTimestamp | HMAC Timestamp | The timestamp generated immediately before the request is generated | integer | 1481496738 |
pstn_HMAC | HMAC Hash | A hash of the request, the HMAC timestamp and the HMAC key | string | abc12345 |
HTTP response
The above request returns on SUCCESS an XML response structured like this:
<?xml version="1.0" standalone="yes"?>
<PaystationFuturePaymentResponse>
<ec>34</ec>
<em>Future Payment Saved Ok</em>
<ti>0085793876-01</ti>
<ct>mastercard</ct>
<merchant_ref/>
<tm>P</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085793876-01</TransactionID>
<PurchaseAmount>0</PurchaseAmount>
<SurchargeAmount/>
<Locale>en</Locale>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-13 11:18:55</TransactionTime>
<PaystationErrorCode>34</PaystationErrorCode>
<PaystationErrorMessage>Future Payment Saved Ok</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>token</TransactionProcess>
<TransactionMode>P</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype>MC</Cardtype>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-13 11:18:55</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime>2017-01-13 11:18:55</DigitalReceiptTime>
<PaystationTransactionID>0085793876-01</PaystationTransactionID>
<FuturePaymentToken>pgv5c65uqa8tj0ig709hj7e63fg8tx1wot4l77pg</FuturePaymentToken>
<FuturePaymentPanGuid>{19B950BB-0C8E-465B-9286-000057EC3E9E}</FuturePaymentPanGuid>
<FuturePaymentPanExpGuid>{FF9551A7-3674-46E3-ABC2-000057EC5C21}</FuturePaymentPanExpGuid>
<IssuerName>unknown</IssuerName>
<IssuerCountry>unknown</IssuerCountry>
</PaystationFuturePaymentResponse>
The above request returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<PaystationFuturePaymentResponse>
<ec>41</ec>
<em>Card number has failed Luhn check</em>
<ti>0085794487-01</ti>
<ct/>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk35fghfghda</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085794487-01</TransactionID>
<PurchaseAmount>0</PurchaseAmount>
<SurchargeAmount/>
<Locale>en</Locale>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-13 11:31:26</TransactionTime>
<PaystationErrorCode>41</PaystationErrorCode>
<PaystationErrorMessage>Card number has failed Luhn check</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>purchase</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype/>
<Username>615043</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-13 11:31:26</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime/>
<PaystationTransactionID/>
<IssuerName>unknown</IssuerName>
<IssuerCountry>unknown</IssuerCountry>
</PaystationFuturePaymentResponse>
Attribute | Name | Description | Type | Example |
---|---|---|---|---|
ec | Error code | The error code status of the transaction | integer | 1 |
em | Error message | The error message status of the transaction | string | Transaction successful |
ti | Transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
ct | Card type | The card issuer | string | mastercard |
merchant_ref | A non-unique identifier that can be assigned to a transaction | string | abc123 | |
tm | Test mode | Denotes if the transaction was completed in test mode or not | string | t |
MerchantSession | Merchant Session ID | A unique value to identify a transaction by | string | abcd-defg-hijk |
UsedAcquirerMerchantID | ||||
TransactionID | Transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
PurchaseAmount | Purchase amount | A positive integer in cent value or alternatively the option specified in the transaction representing the charged amount | positive integer or zero | 5000 |
SurchargeAmount | Surcharge amount | Surcharge amount added to transaction amount | Integer only, default format is cents | 4200 |
Locale | Locale | The language tag represents the language the response text is provided in | string value | en |
ReturnReceiptNumber | Return receipt number | The RRN number is a virtual terminal counter for the transaction and is not unique | integer | 85789579 |
ShoppingTransactionNumber | Shopping transaction number | Is a unique number relating to the Transaction ID (eGate integration's only) | Integer | 85793423 |
AcqResponseCode | Acq response code | Transaction response code from the acquiring bank | Integer | 00 |
QSIResponseCode | QSI response code | Issuing bank response code – the actual raw result from the payment server. Please process transaction result from the PaystationErrorCode | Integer | 0 |
CSCResultCode | CSC result code | The response code in response to verifying the card security code if applicable to transaction | Single character | "M" |
AVSResultCode | AVS result code | Result of any AVS validation. Not supported in New Zealand | Empty | |
TransactionTime | Transaction time | The time the transaction was completed | datetime | 2017-01-13 09:38:26 |
PaystationErrorCode | Error code | The error code status of the transaction | integer | 1 |
PaystationErrorMessage | Error message | The error message status of the transaction | string | Transaction successful |
PaystationExtendedErrorMessage | Extended error message | Extra information regarding the error code if applicable | string value | Refer to card issuer |
MerchantReference | Merchant reference | A non-unique identifier that can be assigned to a transaction | string | abc123 |
CardNo | Card number | A masked card number of the card that completed the transaction | string | 555555XXXXXXX444 |
CardExpiry | Card expiry date | The expiry of the card that completed the transaction | date YYMM | 1705 |
TransactionProcess | Transaction process | The transaction method identification | string | purchase |
TransactionMode | Transaction mode | T or P represents the transaction is a test (T) or production (P) transaction | string value | T |
BatchNumber | Batch number | A four digit number representing the expected settlement date of the transaction in the format MMDD | positive integer | 0013 |
AuthorizeID | Authorize ID | A unique reference provided by the bank to trace the transaction | integer | R81194 |
Cardtype | Card type | The card issuer | string | MC |
Username | Paystation account ID | The Paystation account ID that initiated the transaction | integer | 123456 |
RequestIP | Request ip | The ip used in the initiation of the request | string | 192.168.1.1 |
RequestUserAgent | Request user agent | String that identifies the application client that initiated the transaction request | string | Mozilla/5.0 |
RequestHttpReferrer | Request http referrer | HTTP referrer header if applicable to original transaction request | string value | https://www.example.com |
PaymentRequestTime | Payment request time | The time the transaction was initiated at | datetime | 2017-01-13 09:38:26 |
DigitalOrderTime | Digital order time | Timestamp the transaction URL was created (does not apply to 2-party transactions) | datetime | 2018-03-11 02:40:16 |
DigitalReceiptTime | Digital receipt time | Timestamp the transaction response was received by the card switch | datetime | 2018-03-11 02:40:16 |
PaystationTransactionID | Paystation transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
FuturePaymentToken | Future payment token | A unique identification token assigned to each saved credit card | string | abc123efg456 |
FuturePaymentPanGuid | Future payment pan GUID | A unique id associated with card | ||
FuturePaymentPanExpGuid | Future payment pan exp GUID | A unique id associated with this cards expiry date | ||
IssuerName | Issuer name | The card issuing institution if known | string value | KIWIBANK LIMITED |
IssuerCountry | Issuer country | The country the card was issued if known | string value | NEW ZEALAND |
3 party
Example request
POST https://www.paystation.co.nz/direct/paystation.dll
POST body parameters
paystation=_empty
&pstn_nr=t
&pstn_pi=123456
&pstn_gi=PAYSTATION
&pstn_ms=abcd-defg-hijk
&pstn_fp=t
&pstn_fs=t
HTTP request
POST https://www.paystation.co.nz/direct/paystation.dll
Required POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
paystation | Transaction initiator flag | Required for payment engine | String value | _empty |
pstn_nr | No Redirect flag | Required for payment engine | Single character "t" or "T" | T |
pstn_pi | Paystation ID | The Paystation ID | String value | 612345 |
pstn_gi | Gateway ID | The Gateway ID | String value | PAYSTATION |
pstn_ms | Merchant Session ID | A unique identifier for every transaction attempt | String value (max 64 chars) | qwertyuiop1234567890 |
pstn_fp | Token transaction flag | Required for all token transactions (except independent token refunds) | Single character "t" or "T" | T |
pstn_fs | Token save only flag | Required for token save only transactions | Single character "t" or "T" | T |
Optional POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_am | Amount | Transaction amount | Integer only, default format is cents | 4200 |
pstn_cu | Currency | Currency the transaction will be created in | String value | USD |
pstn_tm | Test mode | Used to create a transaction in test mode | Single character "t" or "T" | T |
pstn_mr | Merchant reference | A non-unique identifier that can be assigned to a transaction | String value (max 64 chars) | abc123 |
pstn_ct | Card type | Stating the card type can bypass the card selection screen of a 3-party transaction | String value (max 64 chars) | visa |
pstn_af | Amount format | Defines the format of the amount | String value "dollars.cents" or "cents" | dollars.cents |
pstn_mc | Customer details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_mo | Order details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_ft | Token name | A unique identifier that credit card details will be stored against (Paystation will generate one if none is provided) | String value (max 64 chars) | qwertyuiop1234567890 |
pstn_du | Dynamic Return URL | The URL to re-direct the customer to after a 3-party transaction | URL encoded string value | https://paymentmaker.com/returnurl |
pstn_dp | Dynamic POST Response URL | The URL to send the POST Response to after a 3-party transaction | URL encoded string value | https://paymentmaker.com/postresponseurl |
pstn_fr | Reseller flag | Allows an account to make a transaction using the token from another account | Single character "t" or "T" | T |
HTTP response
The above request returns on SUCCESS an XML response structured like this:
<?xml version="1.0" standalone="yes"?>
<InitiationRequestResponse>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-13 14:37:55</PaymentRequestTime>
<DigitalOrder>https://payments.paystation.co.nz/hosted/?hk=gaI4CXZMMMQjUXXqmcwXV</DigitalOrder>
<DigitalOrderTime>2017-01-13 14:37:55</DigitalOrderTime>
<DigitalReceiptTime/>
<PaystationTransactionID>0085803098-01</PaystationTransactionID>
</InitiationRequestResponse>
The above request returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<PaystationFuturePaymentResponse>
<ec>41</ec>
<em>Card number has failed Luhn check</em>
<ti>0085794487-01</ti>
<ct/>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk35fghfghda</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085794487-01</TransactionID>
<PurchaseAmount>0</PurchaseAmount>
<SurchargeAmount/>
<Locale>en</Locale>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-13 11:31:26</TransactionTime>
<PaystationErrorCode>41</PaystationErrorCode>
<PaystationErrorMessage>Card number has failed Luhn check</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>purchase</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype/>
<Username>615043</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-13 11:31:26</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime/>
<PaystationTransactionID/>
<IssuerName>unknown</IssuerName>
<IssuerCountry>unknown</IssuerCountry>
</PaystationFuturePaymentResponse>
Attribute | Name | Description | Type | Example |
---|---|---|---|---|
Username | Paystation account ID | The Paystation account ID that initiated the transaction | integer | 123456 |
RequestIP | Request ip | The ip used in the initiation of the request | string | 192.168.1.1 |
RequestUserAgent | Request user agent | String that identifies the application client that initiated the transaction request | string | Mozilla/5.0 |
RequestHttpReferrer | Request http referrer | HTTP referrer header if applicable to original transaction request | string value | https:/www.example.com |
PaymentRequestTime | Payment request time | The time the transaction was initiated at | datetime | 2017-01-13 09:38:26 |
DigitalOrder | Digital order URL | The hosted payment page URL link for the transaction | URL | https://payments.paystation.co.nz/hosted/?hk=12345 |
DigitalOrderTime | Digital order time | Timestamp the transaction URL was created (does not apply to 2-party transactions) | datetime | 2018-03-11 02:40:16 |
DigitalReceiptTime | Digital receipt time | Timestamp the transaction response was received by the card switch | datetime | 2018-03-11 02:40:16 |
PaystationTransactionID | Paystation transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
PayMe
Example request
POST https://www.paystation.co.nz/direct/paystation.dll
POST body parameters
paystation=_empty
&pstn_nr=t
&pstn_pi=123456
&pstn_gi=PAYSTATION
&pstn_2p=t
&pstn_fp=t
&pstn_fs=t
&pstn_co=t
HTTP request
POST https://www.paystation.co.nz/direct/paystation.dll
Required POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
paystation | Transaction initiator flag | Required for payment engine | String value | _empty |
pstn_nr | No Redirect flag | Required for payment engine | Single character "t" or "T" | T |
pstn_pi | Paystation ID | The Paystation ID | String value | 612345 |
pstn_gi | Gateway ID | The Gateway ID | String value | PAYSTATION |
pstn_fp | Token transaction flag | Required for all token transactions (except independent token refunds) | Single character "t" or "T" | T |
pstn_fs | Token save only flag | Required for token save only transactions | Single character "t" or "T" | T |
pstn_co | PayMe order flag | Required for a PayMe transaction | Single character "t" or "T" | T |
Optional POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_cj | PayMe custom fields | Information and custom fields to be displayed on the PayMe order details page | Url encoded string value of JSON format: {"reference": "PayMe reference","description": "A description for a PayMe example","single": "N"} where reference is your identifier (ie: an invoice number), description is the type of reference, and single (Y/N) denotes single payment |
%7B%22reference%22%3A%20%22PayMe%20reference%22%2C%22description%22%3A%20%22A%20description%20for%20a%20PayMe%20example%22%2C%22single%22%3A%20%22N%22%7D |
pstn_am | Amount | Transaction amount | Integer only, default format is cents | 4200 |
pstn_cu | Currency | Currency the transaction will be created in | String value | USD |
pstn_tm | Test mode | Used to create a transaction in test mode | Single character "t" or "T" | T |
pstn_mr | Merchant reference | A non-unique identifier that can be assigned to a transaction | String value (max 64 chars) | abc123 |
pstn_mc | Customer details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_mo | Order details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_ft | Token name | A unique identifier that credit card details will be stored against (Paystation will generate one if none is provided) | String value (max 64 chars) | qwertyuiop1234567890 |
pstn_rf | Return format | Defines the response format from Paystation (default is XML) | String value | JSON |
pstn_tc | Terms and conditions flag | Will add to our hosted page a tick box and a link to the merchants T&Cs | Single character "t" or "T" | T |
HTTP response
The above request returns on SUCCESS an XML response structured like this:
<?xml version="1.0" standalone="yes"?>
<InitiationRequestResponse>
<Username>615043</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 09:52:52</PaymentRequestTime>
<DigitalOrder>https://payments.paystation.co.nz/hosted/?hk=beHO8FXH7X7sPO-DAG</DigitalOrder>
<DigitalOrderTime>2017-01-16 09:52:52</DigitalOrderTime>
<DigitalReceiptTime/>
<PaystationTransactionID>0085900388-01</PaystationTransactionID>
</InitiationRequestResponse>
The above request returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<PaystationFuturePaymentResponse>
<ec>13</ec>
<em>Transaction already in progress</em>
<ti>0085900404-01</ti>
<ct/>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085900404-01</TransactionID>
<PurchaseAmount>0</PurchaseAmount>
<SurchargeAmount/>
<Locale>en</Locale>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 09:53:16</TransactionTime>
<PaystationErrorCode>13</PaystationErrorCode>
<PaystationErrorMessage>Transaction already in progress</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>purchase</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype/>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 09:53:16</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime/>
<PaystationTransactionID/>
</PaystationFuturePaymentResponse>
Attribute | Name | Description | Type | Example |
---|---|---|---|---|
PayMeOrderURL | PayMe order URL | The hosted payment page URL link for the transaction | URL | https://payments.paystation.co.nz/hosted/?hk=12345 |
PayMeOrderID | PayMe order ID | A unique identifier assigned to each PayMe transaction | integer | 12345 |
ec | Error code | The error code status of the transaction | integer | 1 |
em | Error message | The error message status of the transaction | string | Transaction successful |
PaystationErrorCode | Error code | The error code status of the transaction | integer | 1 |
PaystationErrorMessage | Error message | The error message status of the transaction | string | Transaction successful |
RequestIP | Request ip | The ip used in the initiation of the request | string | 192.168.1.1 |
Token initiator
A token initiator allows for an amount to be charged against a card in a purchase, or set aside as an authorisation (verifying the card), at the same time, the card details are stored in our card vault for recurring billing.
2 party
This endpoint is used for initiating a token, this is a 2 party transaction only
Example request
POST https://www.paystation.co.nz/direct/paystation.dll
POST body parameters
paystation=_empty
&pstn_nr=t
&pstn_pi=123456
&pstn_gi=PAYSTATION
&pstn_ms=abcd-defg-hijk
&pstn_am=5000
&pstn_2p=t
&pstn_fp=t
&pstn_cn=5555555555554444
&pstn_ex=1705
HTTP request
POST https://www.paystation.co.nz/direct/paystation.dll
Required POST body parameters
Parameter | Name | Description | Example |
---|---|---|---|
paystation | Transaction initiator flag | Required for payment engine | _empty |
pstn_nr | No Redirect flag | Required for payment engine | T |
pstn_pi | Paystation ID | The Paystation ID or Alternative Paystation ID | 612345 |
pstn_gi | Gateway ID | The Gateway ID | PAYSTATION |
pstn_ms | Merchant Session ID | A unique identifier for every transaction attempt | qwertyuiop1234567890 |
pstn_am | Amount | Transaction amount (default is cents) | 4200 |
pstn_2p | Two party flag | Required for 2-party transactions | T |
pstn_fp | Token transaction flag | Required for all token transactions except independent token refunds | T |
pstn_cn | Card Number | Credit/debit card number (13 - 19 characters) | 51234567896789346 |
pstn_ex | Card expiry date | Four character expiry date (default is YYMM) | 1705 |
Optional POST body parameters
Parameter | Name | Description | Example |
---|---|---|---|
pstn_am | Amount | Transaction amount (default is cents) | 4200 |
pstn_cu | Currency | Currency the transaction will be created in | USD |
pstn_tm | Test Mode | Used to create a transaction in test mode | T |
pstn_mr | Merchant reference | A non-unique identifier that can be assigned to a transaction | Cool Stories |
pstn_ct | Card type | Stating the card type can bypass the card selection screen of a 3-party transaction | visa |
pstn_df | Card expiry date format | Defines the format of the expiry date | MMYY |
pstn_af | Amount format | Defines the format of the amount | dollars.cents |
pstn_mc | Customer details | A non-unique identifier that can be assigned to a transaction | abc123 |
pstn_mo | Order details | Credit/debit card number (13 - 19 characters) | Dumplings |
pstn_ft | Token ID | A unique identifier that credit card details will be stored against (Paystation will provide one if none is provided) | |
pstn_cc | Card security code | Three/Four digit code found on back of credit/debit card | 100 |
pstn_fr | Reseller flag | Allows an account to make a transaction using the token from another account (requires admin configuration) | |
pstn_rf | Return format | Defines the response format from Paystation (default is XML) | JSON |
Optional query string parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_HMACTimestamp | HMAC Timestamp | The timestamp generated immediately before the request is generated | integer | 1481496738 |
pstn_HMAC | HMAC Hash | A hash of the request, the HMAC timestamp and the HMAC key | string | abc12345 |
Return response
The above request returns on SUCCESS an XML response structured like this:
<?xml version="1.0" standalone="yes"?>
<PaystationFuturePaymentResponse>
<ec>34</ec>
<em>Future Payment Saved Ok</em>
<ti>0085900660-01</ti>
<ct>mastercard</ct>
<merchant_ref/>
<tm>P</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085900660-01</TransactionID>
<PurchaseAmount>5000</PurchaseAmount>
<SurchargeAmount/>
<Locale>en</Locale>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 09:58:53</TransactionTime>
<PaystationErrorCode>34</PaystationErrorCode>
<PaystationErrorMessage>Future Payment Saved Ok</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>token</TransactionProcess>
<TransactionMode>P</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype>MC</Cardtype>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 09:58:53</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime>2017-01-16 09:58:53</DigitalReceiptTime>
<PaystationTransactionID>0085900660-01</PaystationTransactionID>
<FuturePaymentToken>8421o52s18qdn0j1rnc8b23q35a8va93jfld0l31vvx7arxbi2y807cb6vy7v9xo</FuturePaymentToken>
<FuturePaymentPanGuid>{19B950BB-0C8E-465B-9286-000057EC3E9E}</FuturePaymentPanGuid>
<FuturePaymentPanExpGuid>{FF9551A7-3674-46E3-ABC2-000057EC5C21}</FuturePaymentPanExpGuid>
<IssuerName>unknown</IssuerName>
<IssuerCountry>unknown</IssuerCountry>
</PaystationFuturePaymentResponse>
The above request returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<PaystationFuturePaymentResponse>
<ec>13</ec>
<em>Transaction already in progress</em>
<ti>0085900404-01</ti>
<ct/>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085900404-01</TransactionID>
<PurchaseAmount>0</PurchaseAmount>
<SurchargeAmount/>
<Locale>en</Locale>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 09:53:16</TransactionTime>
<PaystationErrorCode>13</PaystationErrorCode>
<PaystationErrorMessage>Transaction already in progress</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>purchase</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype/>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 09:53:16</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime/>
<PaystationTransactionID/>
</PaystationFuturePaymentResponse>
Attribute | Name | Description | Type | Example |
---|---|---|---|---|
ec | Error code | The error code status of the transaction | integer | 1 |
em | Error message | The error message status of the transaction | string | Transaction successful |
ti | Transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
ct | Card type | The card issuer | string | mastercard |
merchant_ref | A non-unique identifier that can be assigned to a transaction | string | abc123 | |
tm | Test mode | Denotes if the transaction was completed in test mode or not | string | t |
MerchantSession | Merchant Session ID | A unique value to identify a transaction by | string | abcd-defg-hijk |
UsedAcquirerMerchantID | ||||
TransactionID | Transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
PurchaseAmount | Purchase amount | A positive integer in cent value or alternatively the option specified in the transaction representing the charged amount | positive integer or zero | 5000 |
SurchargeAmount | Surcharge amount | Surcharge amount added to transaction amount | Integer only, default format is cents | 4200 |
Locale | Locale | The language tag represents the language the response text is provided in | string value | en |
ReturnReceiptNumber | Return receipt number | The RRN number is a virtual terminal counter for the transaction and is not unique | integer | 85789579 |
ShoppingTransactionNumber | Shopping transaction number | Is a unique number relating to the Transaction ID (eGate integration's only) | Integer | 85793423 |
AcqResponseCode | Acq response code | Transaction response code from the acquiring bank | Integer | 00 |
QSIResponseCode | QSI response code | Issuing bank response code – the actual raw result from the payment server. Please process transaction result from the PaystationErrorCode | Integer | 0 |
CSCResultCode | CSC result code | The response code in response to verifying the card security code if applicable to transaction | Single character | "M" |
AVSResultCode | AVS result code | Result of any AVS validation. Not supported in New Zealand | Empty | |
TransactionTime | Transaction time | The time the transaction was completed | datetime | 2017-01-13 09:38:26 |
PaystationErrorCode | Error code | The error code status of the transaction | integer | 1 |
PaystationErrorMessage | Error message | The error message status of the transaction | string | Transaction successful |
PaystationExtendedErrorMessage | Extended error message | Extra information regarding the error code if applicable | string value | Refer to card issuer |
MerchantReference | Merchant reference | A non-unique identifier that can be assigned to a transaction | string | abc123 |
CardNo | Card number | A masked card number of the card that completed the transaction | string | 555555XXXXXXX444 |
CardExpiry | Card expiry date | The expiry of the card that completed the transaction | date YYMM | 1705 |
TransactionProcess | Transaction process | The transaction method identification | string | purchase |
TransactionMode | Transaction mode | T or P represents the transaction is a test (T) or production (P) transaction | string value | T |
BatchNumber | Batch number | A four digit number representing the expected settlement date of the transaction in the format MMDD | date MMDD | 0518 |
AuthorizeID | Authorize ID | A unique reference provided by the bank to trace the transaction | string value | R81194 |
Cardtype | Card type | The card issuer | string | MC |
Username | Paystation account ID | The Paystation account ID that initiated the transaction | integer | 123456 |
RequestIP | Request ip | The ip used in the initiation of the request | string | 192.168.1.1 |
RequestUserAgent | Request user agent | String that identifies the application client that initiated the transaction request | string | Mozilla/5.0 |
RequestHttpReferrer | Request http referrer | HTTP referrer header if applicable to original transaction request | string value | https://www.example.com |
PaymentRequestTime | Payment request time | The time the transaction was initiated at | datetime | 2017-01-13 09:38:26 |
DigitalOrderTime | Digital order time | Timestamp the transaction URL was created (does not apply to 2-party transactions) | datetime | 2018-03-11 02:40:16 |
DigitalReceiptTime | Digital receipt time | Timestamp the transaction response was received by the card switch | datetime | 2018-03-11 02:40:16 |
PaystationTransactionID | Paystation transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
FuturePaymentToken | Future payment token | A unique identification token assigned to each saved credit card | string | abc123efg456 |
FuturePaymentPanGuid | Future payment pan GUID | A unique id associated with card | ||
FuturePaymentPanExpGuid | Future payment pan exp GUID | A unique id associated with this cards expiry date | ||
IssuerName | Issuer name | The card issuing institution if known | string value | KIWIBANK LIMITED |
IssuerCountry | Issuer country | The country the card was issued if known | string value | NEW ZEALAND |
3 party
Example request
POST https://www.paystation.co.nz/direct/paystation.dll
POST body parameters
paystation=_empty
&pstn_nr=t
&pstn_pi=123456
&pstn_gi=PAYSTATION
&pstn_ms=abcd-defg-hijk
&pstn_am=5000
&pstn_fp=t
HTTP request
POST https://www.paystation.co.nz/direct/paystation.dll
Required POST body parameters
Parameter | Name | Description | Example |
---|---|---|---|
paystation | Transaction initiator flag | Required for payment engine | _empty |
pstn_nr | No Redirect flag | Required for payment engine | T |
pstn_pi | Paystation ID | The Paystation ID or Alternative Paystation ID | 612345 |
pstn_gi | Gateway ID | The Gateway ID | PAYSTATION |
pstn_ms | Merchant Session ID | A unique identifier for every transaction attempt | qwertyuiop1234567890 |
pstn_am | Amount | Transaction amount (default is cents) | 4200 |
pstn_fp | Token transaction flag | Required for all token transactions except independent token refunds | T |
Optional POST body parameters
Parameter | Name | Description | Example |
---|---|---|---|
pstn_cu | Currency | Currency the transaction will be created in | USD |
pstn_tm | Test Mode | Used to create a transaction in test mode | T |
pstn_mr | Merchant reference | A non-unique identifier that can be assigned to a transaction | Cool Stories |
pstn_ct | Card type | Stating the card type can bypass the card selection screen of a 3-party transaction | visa |
pstn_af | Amount format | Defines the format of the amount | dollars.cents |
pstn_mc | Customer details | A non-unique identifier that can be assigned to a transaction | abc123 |
pstn_mo | Order details | Credit/debit card number (13 - 19 characters) | Dumplings |
pstn_ft | Token ID | A unique identifier that credit card details will be stored against (Paystation will provide one if none is provided) | |
pstn_du | Dynamic Return URL | The URL to re-direct the customer to after a 3-party transaction | https://paymentmaker.com/returnurl |
pstn_dp | Dynamic POST Response URL | The URL to send the POST Response to after a 3-party transaction | https://paymentmaker.com/postresponseurl |
pstn_fr | Reseller flag | Allows an account to make a transaction using the token from another account (requires admin configuration) |
Return response
The above request returns on SUCCESS an XML response structured like this:
<?xml version="1.0" standalone="yes"?>
<InitiationRequestResponse>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 10:09:58</PaymentRequestTime>
<DigitalOrder>https://payments.paystation.co.nz/hosted/?hk=G9M5-4jruLbIovSG8RGpdiqMVg0r1hU</DigitalOrder>
<DigitalOrderTime>2017-01-16 10:09:58</DigitalOrderTime>
<DigitalReceiptTime/>
<PaystationTransactionID>0085901133-01</PaystationTransactionID>
</InitiationRequestResponse>
The above request returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<PaystationFuturePaymentResponse>
<ec>13</ec>
<em>Transaction already in progress</em>
<ti>0085900404-01</ti>
<ct/>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085900404-01</TransactionID>
<PurchaseAmount>0</PurchaseAmount>
<SurchargeAmount/>
<Locale>en</Locale>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 09:53:16</TransactionTime>
<PaystationErrorCode>13</PaystationErrorCode>
<PaystationErrorMessage>Transaction already in progress</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>purchase</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype/>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 09:53:16</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime/>
<PaystationTransactionID/>
</PaystationFuturePaymentResponse>
Attribute | Name | Description | Type | Example |
---|---|---|---|---|
Username | Paystation account ID | The Paystation account ID that initiated the transaction | integer | 123456 |
RequestIP | Request ip | The ip used in the initiation of the request | string | 192.168.1.1 |
RequestUserAgent | Request user agent | String that identifies the application client that initiated the transaction request | string | Mozilla/5.0 |
RequestHttpReferrer | Request http referrer | HTTP referrer header if applicable to original transaction request | string value | https://www.example.com |
PaymentRequestTime | Payment request time | The time the transaction was initiated at | datetime | 2017-01-13 09:38:26 |
DigitalOrder | Digital order URL | The hosted payment page URL link for the transaction | URL | https://payments.paystation.co.nz/hosted/?hk=12345 |
DigitalOrderTime | Digital order time | Timestamp the transaction URL was created (does not apply to 2-party transactions) | datetime | 2018-03-11 02:40:16 |
DigitalReceiptTime | Digital receipt time | Timestamp the transaction response was received by the card switch | datetime | 2018-03-11 02:40:16 |
PaystationTransactionID | Paystation transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
PayMe
Example request
POST https://www.paystation.co.nz/direct/paystation.dll
POST body parameters
paystation=_empty
&pstn_nr=t
&pstn_pi=123456
&pstn_gi=PAYSTATION
&pstn_am=5000
&pstn_fp=t
&pstn_fs=t
&pstn_co=t
HTTP request
POST https://www.paystation.co.nz/direct/paystation.dll
Required POST body parameters
Parameter | Name | Description | Example |
---|---|---|---|
paystation | Transaction initiator flag | Required for payment engine | _empty |
pstn_nr | No Redirect flag | Required for payment engine | T |
pstn_pi | Paystation ID | The Paystation ID or Alternative Paystation ID | 612345 |
pstn_gi | Gateway ID | The Gateway ID | PAYSTATION |
pstn_fp | Token transaction flag | Required for all token transactions except independent token refunds | T |
pstn_fs | Token save only flag | Required for token save only transactions | T |
pstn_co | PayMe order flag | Required for a PayMe transaction | T |
Optional POST body parameters
Parameter | Name | Description | Example |
---|---|---|---|
pstn_am | Amount | Transaction amount (default is cents) | 4200 |
pstn_cu | Currency | Currency the transaction will be created in | USD |
pstn_tm | Test Mode | Used to create a transaction in test mode | T |
pstn_mr | Merchant reference | A non-unique identifier that can be assigned to a transaction | Cool Stories |
pstn_af | Amount format | Defines the format of the amount | dollars.cents |
pstn_mc | Customer details | A non-unique identifier that can be assigned to a transaction | abc123 |
pstn_mo | Order details | Credit/debit card number (13 - 19 characters) | Dumplings |
pstn_ft | Token ID | A unique identifier that credit card details will be stored against (Paystation will provide one if none is provided) | |
pstn_rt | Refund transaction ID | The transaction ID to be refunded | 0066758901-01 |
pstn_fr | Reseller flag | Allows an account to make a transaction using the token from another account (requires admin configuration) | T |
pstn_fr | Reseller flag | Allows an account to make a transaction using the token from another account (requires admin configuration) | |
pstn_cj | PayMe custom fields | Information and custom fields to be displayed on the PayMe order details page. Url encoded string value of JSON format: {"reference": "PayMe reference","description": "A description for a PayMe example","single": "N"} where reference is your identifier (ie: an invoice number), description is the type of reference, and single (Y/N) denotes single payment |
%7B%22reference%22%3A%20%22PayMe%20reference%22%2C%22description%22%3A%20%22A%20description%20for%20a%20PayMe%20example%22%2C%22single%22%3A%20%22N%22%7D |
Return response
The above request returns on SUCCESS an XML response structured like this:
<?xml version="1.0" standalone="yes"?>
<InitiationRequestResponse>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 10:13:13</PaymentRequestTime>
<DigitalOrder>https://payments.paystation.co.nz/hosted/?hk=TXGa_JyURVfxudQTDBztRElCfQ</DigitalOrder>
<DigitalOrderTime>2017-01-16 10:13:13</DigitalOrderTime>
<DigitalReceiptTime/>
<PaystationTransactionID>0085901352-01</PaystationTransactionID>
</InitiationRequestResponse>
The above request returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<PaystationFuturePaymentResponse>
<ec>13</ec>
<em>Transaction already in progress</em>
<ti>0085900404-01</ti>
<ct/>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085900404-01</TransactionID>
<PurchaseAmount>0</PurchaseAmount>
<SurchargeAmount/>
<Locale>en</Locale>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 09:53:16</TransactionTime>
<PaystationErrorCode>13</PaystationErrorCode>
<PaystationErrorMessage>Transaction already in progress</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>purchase</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype/>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 09:53:16</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime/>
<PaystationTransactionID/>
</PaystationFuturePaymentResponse>
Attribute | Name | Description | Type | Example |
---|---|---|---|---|
Username | Paystation account ID | The Paystation account ID that initiated the transaction | integer | 123456 |
RequestIP | Request ip | The ip used in the initiation of the request | string | 192.168.1.1 |
RequestUserAgent | Request user agent | String that identifies the application client that initiated the transaction request | string | Mozilla/5.0 |
RequestHttpReferrer | Request http referrer | HTTP referrer header if applicable to original transaction request | string value | https://www.example.com |
PaymentRequestTime | Payment request time | The time the transaction was initiated at | datetime | 2017-01-13 09:38:26 |
DigitalOrder | Digital order URL | The hosted payment page URL link for the transaction | URL | https://payments.paystation.co.nz/hosted/?hk=12345 |
DigitalOrderTime | Digital order time | Timestamp the transaction URL was created (does not apply to 2-party transactions) | datetime | 2018-03-11 02:40:16 |
DigitalReceiptTime | Digital receipt time | Timestamp the transaction response was received by the card switch | datetime | 2018-03-11 02:40:16 |
PaystationTransactionID | Paystation transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
Token initiator + auth
A token initiator allows for full or partial payment - you to either complete a purchase or authorization against a card (verifying the details are correct) and at the same time the card details are stored in our card vault for recurring billing
2 party
This endpoint is used for initiating a token with authorisation, this is a 2 party transaction only
Example request
POST https://www.paystation.co.nz/direct/paystation.dll
POST body parameters
paystation=_empty
&pstn_nr=t
&pstn_pi=123456
&pstn_gi=PAYSTATION
&pstn_ms=abcd-defg-hijk
&pstn_am=5000
&pstn_2p=t
&pstn_fp=t
&pstn_fs=t
&pstn_cn=5555555555554444
&pstn_ex=1705
&pstn_pa=t
HTTP request
POST https://www.paystation.co.nz/direct/paystation.dll
Required POST body parameters
Parameter | Name | Description | Example |
---|---|---|---|
paystation | Transaction initiator flag | Required for payment engine | String value |
pstn_nr | No Redirect flag | Required for payment engine | Single character "t" or "T" |
pstn_pi | Paystation ID | The Paystation ID | String value |
pstn_gi | Gateway ID | The Gateway ID | String value |
pstn_ms | Merchant Session ID | A unique identifier for every transaction attempt | String value (max 64 chars) |
pstn_2p | Two party flag | Required for 2-party transactions | Single character "t" or "T" |
pstn_fp | Token transaction flag | Required for all token transactions except independent token refunds | T |
pstn_fp | Token transaction flag | Required for all token transactions (except independent token refunds) | Single character "t" or "T" |
pstn_cn | Card number | Credit/debit card number (13 - 19 characters) | Integer, no spaces in between card numbers |
pstn_ex | Card expiry date | Four character expiry date | Integer, no spaces in between year and month (default is yymm format) |
pstn_pa | Authorisation flag | Required for authorisation transactions | Single character "t" or "T" |
Optional POST body parameters
Parameter | Name | Description | Example |
---|---|---|---|
pstn_am | Amount | Transaction amount | Integer only, default format is cents |
pstn_cu | Currency | Currency the transaction will be created in | String value |
pstn_tm | Test mode | Used to create a transaction in test mode | Single character "t" or "T" |
pstn_mr | Merchant reference | A non-unique identifier that can be assigned to a transaction | String value (max 64 chars) |
pstn_ct | Card type | Stating the card type can bypass the card selection screen of a 3-party transaction | String value (max 64 chars) |
pstn_df | Card expiry date format | Defines the format of the expiry date | "mmyy" or "yymm" |
pstn_af | Amount format | Defines the format of the amount | String value "dollars.cents" or "cents" |
pstn_mc | Customer details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) |
pstn_mo | Order details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) |
pstn_ft | Token ID | A unique identifier that credit card details will be stored against (Paystation will provide one if none is provided) | String value (max 64 chars) |
pstn_cc | Card security code | Three/Four digit code found on back of credit/debit card | String value |
pstn_fr | Reseller flag | Allows an account to make a transaction using the token from another account | Single character "t" or "T" |
pstn_rf | Return format | Defines the response format from Paystation (default is XML) | String value |
Optional query string parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_HMACTimestamp | HMAC Timestamp | The timestamp generated immediately before the request is generated | integer | 1481496738 |
pstn_HMAC | HMAC Hash | A hash of the request, the HMAC timestamp and the HMAC key | string | abc12345 |
Return response
The above request returns on SUCCESS an XML response structured like this:
<?xml version="1.0" standalone="yes"?>
<PaystationFuturePaymentResponse>
<ec>34</ec>
<em>Future Payment Saved Ok</em>
<ti>0085901575-01</ti>
<ct>mastercard</ct>
<merchant_ref/>
<tm>P</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085901575-01</TransactionID>
<PurchaseAmount>5000</PurchaseAmount>
<SurchargeAmount/>
<Locale>en</Locale>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 10:19:02</TransactionTime>
<PaystationErrorCode>34</PaystationErrorCode>
<PaystationErrorMessage>Future Payment Saved Ok</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>token</TransactionProcess>
<TransactionMode>P</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype>MC</Cardtype>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 10:19:02</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime>2017-01-16 10:19:02</DigitalReceiptTime>
<PaystationTransactionID>0085901575-01</PaystationTransactionID>
<FuturePaymentToken>7q710g0h694xljdqi6p6v2ff65r129k38frwnn550v32p6r00ykx4jbp09r0yx6n</FuturePaymentToken>
<FuturePaymentPanGuid>{19B950BB-0C8E-465B-9286-000057EC3E9E}</FuturePaymentPanGuid>
<FuturePaymentPanExpGuid>{FF9551A7-3674-46E3-ABC2-000057EC5C21}</FuturePaymentPanExpGuid>
<IssuerName>unknown</IssuerName>
<IssuerCountry>unknown</IssuerCountry>
</PaystationFuturePaymentResponse>
The above request returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<PaystationFuturePaymentResponse>
<ec>13</ec>
<em>Transaction already in progress</em>
<ti>0085900404-01</ti>
<ct/>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085900404-01</TransactionID>
<PurchaseAmount>0</PurchaseAmount>
<SurchargeAmount/>
<Locale>en</Locale>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 09:53:16</TransactionTime>
<PaystationErrorCode>13</PaystationErrorCode>
<PaystationErrorMessage>Transaction already in progress</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>purchase</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype/>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 09:53:16</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime/>
<PaystationTransactionID/>
</PaystationFuturePaymentResponse>
3 party
Example request
POST https://www.paystation.co.nz/direct/paystation.dll
POST body parameters
paystation=_empty
&pstn_nr=t
&pstn_pi=123456
&pstn_gi=PAYSTATION
&pstn_ms=abcd-defg-hijk
&pstn_am=5000
&pstn_fp=t
The above request returns on SUCCESS an XML response structured like this:
<?xml version="1.0" standalone="yes"?>
<InitiationRequestResponse>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 10:09:58</PaymentRequestTime>
<DigitalOrder>https://payments.paystation.co.nz/hosted/?hk=G9M5-4jruLbIovSG8RGpdiqMVg0r1hU</DigitalOrder>
<DigitalOrderTime>2017-01-16 10:09:58</DigitalOrderTime>
<DigitalReceiptTime/>
<PaystationTransactionID>0085901133-01</PaystationTransactionID>
</InitiationRequestResponse>
The above request returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<PaystationFuturePaymentResponse>
<ec>13</ec>
<em>Transaction already in progress</em>
<ti>0085900404-01</ti>
<ct/>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085900404-01</TransactionID>
<PurchaseAmount>0</PurchaseAmount>
<SurchargeAmount/>
<Locale>en</Locale>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 09:53:16</TransactionTime>
<PaystationErrorCode>13</PaystationErrorCode>
<PaystationErrorMessage>Transaction already in progress</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>purchase</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype/>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 09:53:16</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime/>
<PaystationTransactionID/>
</PaystationFuturePaymentResponse>
HTTP Request
POST https://www.paystation.co.nz/direct/paystation.dll
Required POST body parameters
Parameter | Name | Description | Example |
---|---|---|---|
paystation | Transaction initiator flag | Required for payment engine | String value |
pstn_nr | No Redirect flag | Required for payment engine | Single character "t" or "T" |
pstn_pi | Paystation ID | The Paystation ID | String value |
pstn_gi | Gateway ID | The Gateway ID | String value |
pstn_ms | Merchant Session ID | A unique identifier for every transaction attempt | String value (max 64 chars) |
pstn_am | Amount | Transaction amount | Integer only, default format is cents |
pstn_fp | Token transaction flag | Required for all token transactions (except independent token refunds) | Single character "t" or "T" |
pstn_pa | Authorisation flag | Required for authorisation transactions | Single character "t" or "T" |
Optional POST body parameters
Parameter | Name | Description | Example |
---|---|---|---|
pstn_cu | Currency | Currency the transaction will be created in | USD |
pstn_tm | Test Mode | Used to create a transaction in test mode | T |
pstn_mr | Merchant reference | A non-unique identifier that can be assigned to a transaction | Cool Stories |
pstn_ct | Card type | Stating the card type can bypass the card selection screen of a 3-party transaction | visa |
pstn_af | Amount format | Defines the format of the amount | dollars.cents |
pstn_mc | Customer details | A non-unique identifier that can be assigned to a transaction | abc123 |
pstn_mo | Order details | Credit/debit card number (13 - 19 characters) | Dumplings |
pstn_ft | Token ID | A unique identifier that credit card details will be stored against (Paystation will provide one if none is provided) | |
pstn_du | Dynamic Return URL | The URL to re-direct the customer to after a 3-party transaction | https://paymentmaker.com/returnurl |
pstn_dp | Dynamic POST Response URL | The URL to send the POST Response to after a 3-party transaction | https://paymentmaker.com/postresponseurl |
pstn_fr | Reseller flag | Allows an account to make a transaction using the token from another account (requires admin configuration) |
Token bill
A token bill is a purchase against a saved card.
2 party
Example request
POST https://www.paystation.co.nz/direct/paystation.dll
POST body parameters
paystation=_empty
&pstn_nr=t
&pstn_pi=123456
&pstn_gi=PAYSTATION
&pstn_ms=abcd-defg-hijk
&pstn_am=5000
&pstn_2p=t
&pstn_fp=t
&pstn_ft=17m3tf56z3j9w171784id6vn92232ry4x2qvkh2bk9s7ww0y85bv3mm17109o66c
This endpoint is used for billing a stored token, this is a 2 party transaction only
HTTP request
POST https://www.paystation.co.nz/direct/paystation.dll
Required POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
paystation | Transaction initiator flag | Required for payment engine | String value | _empty |
pstn_nr | No Redirect flag | Required for payment engine | Single character "t" or "T" | T |
pstn_pi | Paystation ID | The Paystation ID | String value | 612345 |
pstn_gi | Gateway ID | The Gateway ID | String value | PAYSTATION |
pstn_ms | Merchant Session ID | A unique identifier for every transaction attempt | String value (max 64 chars) | qwertyuiop1234567890 |
pstn_am | Amount | Transaction amount | Integer only, default format is cents | 4200 |
pstn_2p | Two party flag | Required for 2-party transactions | Single character "t" or "T" | T |
pstn_fp | Token transaction flag | Required for all token transactions (except independent token refunds) | Single character "t" or "T" | T |
pstn_ft | Token name | A unique identifier that credit card details will be stored against (Paystation will generate one if none is provided) | String value (max 64 chars) | qwertyuiop1234567890 |
Optional POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_cu | Currency | Currency the transaction will be created in | String value | USD |
pstn_tm | Test mode | Used to create a transaction in test mode | Single character "t" or "T" | T |
pstn_mr | Merchant reference | A non-unique identifier that can be assigned to a transaction | String value (max 64 chars) | abc123 |
pstn_af | Amount format | Defines the format of the amount | String value "dollars.cents" or "cents" | dollars.cents |
pstn_mc | Customer details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_mo | Order details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_cc | Card security code | Three/Four digit code found on back of credit/debit card | String value | 100 |
pstn_fr | Reseller flag | Allows an account to make a transaction using the token from another account | Single character "t" or "T" | T |
pstn_rf | Return format | Defines the response format from Paystation (default is XML) | String value | JSON |
Optional query string parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_HMACTimestamp | HMAC Timestamp | The timestamp generated immediately before the request is generated | integer | 1481496738 |
pstn_HMAC | HMAC Hash | A hash of the request, the HMAC timestamp and the HMAC key | string | abc12345 |
Return response
The above request returns on SUCCESS an XML response structured like this:
<?xml version="1.0" standalone="yes"?>
<PaystationFuturePaymentResponse>
<FuturePaymentToken>17m3tf56z3j9w171784id6vn92232ry4x2qvkh2bk9s7ww0y85bv3mm17109o66c</FuturePaymentToken>
<FuturePaymentPanGuid>{19B950BB-0C8E-465B-9286-000057EC3E9E}</FuturePaymentPanGuid>
<FuturePaymentPanExpGuid>{FF9551A7-3674-46E3-ABC2-000057EC5C21}</FuturePaymentPanExpGuid>
<ec>0</ec>
<em>Transaction successful</em>
<ti>0085901808-01</ti>
<ct>mastercard</ct>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085901808-01</TransactionID>
<PurchaseAmount>5000</PurchaseAmount>
<SurchargeAmount/>
<Locale/>
<ReturnReceiptNumber>85901808</ReturnReceiptNumber>
<ShoppingTransactionNumber/>
<AcqResponseCode>00</AcqResponseCode>
<QSIResponseCode>0</QSIResponseCode>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 10:24:31</TransactionTime>
<PaystationErrorCode>0</PaystationErrorCode>
<PaystationErrorMessage>Transaction successful</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<CardNo>555555XXXXXXX444</CardNo>
<CardExpiry>1705</CardExpiry>
<TransactionProcess>purchase</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber>0116</BatchNumber>
<AuthorizeID/>
<Cardtype>MC</Cardtype>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 10:24:30</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime>2017-01-16 10:24:31</DigitalReceiptTime>
<PaystationTransactionID>0085901808-01</PaystationTransactionID>
<FuturePaymentToken>17m3tf56z3j9w171784id6vn92232ry4x2qvkh2bk9s7ww0y85bv3mm17109o66c</FuturePaymentToken>
<FuturePaymentPanGuid>{19B950BB-0C8E-465B-9286-000057EC3E9E}</FuturePaymentPanGuid>
<FuturePaymentPanExpGuid>{FF9551A7-3674-46E3-ABC2-000057EC5C21}</FuturePaymentPanExpGuid>
<IssuerName>unknown</IssuerName>
<IssuerCountry>unknown</IssuerCountry>
</PaystationFuturePaymentResponse>
The above request returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<PaystationFuturePaymentResponse>
<ec>13</ec>
<em>Transaction already in progress</em>
<ti>0085900404-01</ti>
<ct/>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085900404-01</TransactionID>
<PurchaseAmount>0</PurchaseAmount>
<SurchargeAmount/>
<Locale>en</Locale>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 09:53:16</TransactionTime>
<PaystationErrorCode>13</PaystationErrorCode>
<PaystationErrorMessage>Transaction already in progress</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>purchase</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype/>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 09:53:16</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime/>
<PaystationTransactionID/>
</PaystationFuturePaymentResponse>
Attribute | Name | Description | Type | Example |
---|---|---|---|---|
ec | Error code | The error code status of the transaction | integer | 1 |
em | Error message | The error message status of the transaction | string | Transaction successful |
ti | Transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
ct | Card type | The card issuer | string | mastercard |
merchant_ref | A non-unique identifier that can be assigned to a transaction | string | abc123 | |
tm | Test mode | Denotes if the transaction was completed in test mode or not | string | t |
MerchantSession | Merchant Session ID | A unique value to identify a transaction by | string | abcd-defg-hijk |
UsedAcquirerMerchantID | ||||
TransactionID | Transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
PurchaseAmount | Purchase amount | A positive integer in cent value or alternatively the option specified in the transaction representing the charged amount | positive integer or zero | 5000 |
SurchargeAmount | Surcharge amount added to transaction amount | Integer only, default format is cents | 4200 | |
Locale | Locale | The language tag represents the language the response text is provided in | string value | en |
ReturnReceiptNumber | Return receipt number | The RRN number is a virtual terminal counter for the transaction and is not unique | positive 8 digit number | 85789579 |
ShoppingTransactionNumber | Shopping transaction number | Is a unique number relating to the Transaction ID (eGate integration's only) | Integer | 85793423 |
AcqResponseCode | Acq response code | Transaction response code from the acquiring bank | Integer | 00 |
QSIResponseCode | QSI response code | Issuing bank response code – the actual raw result from the payment server. Please process transaction result from the PaystationErrorCode | Integer | 0 |
CSCResultCode | CSC result code | The response code in response to verifying the card security code if applicable to transaction | Single character | "M" |
AVSResultCode | AVS result code | Result of any AVS validation. Not supported in New Zealand | Empty | |
TransactionTime | Transaction time | The time the transaction was completed | datetime | 2017-01-13 09:38:26 |
PaystationErrorCode | Error code | The error code status of the transaction | integer | 1 |
PaystationErrorMessage | Error message | The error message status of the transaction | string | Transaction successful |
PaystationExtendedErrorMessage | Extended error message | Extra information regarding the error code if applicable | string value | Refer to card issuer |
MerchantReference | Merchant reference | A non-unique identifier that can be assigned to a transaction | string | abc123 |
CardNo | Card number | A masked card number of the card that completed the transaction | string | 555555XXXXXXX444 |
CardExpiry | Card expiry date | The expiry of the card that completed the transaction | date YYMM | 1705 |
TransactionProcess | Transaction process | The transaction method identification | string | purchase |
TransactionMode | Transaction mode | T or P represents the transaction is a test (T) or production (P) transaction | string value | T |
BatchNumber | Batch number | A four digit number representing the expected settlement date of the transaction in the format MMDD | positive integer | 0013 |
AuthorizeID | Authorize ID | A unique reference provided by the bank to trace the transaction | integer | R81194 |
Cardtype | Card type | The card issuer | string | MC |
Username | Paystation account ID | The Paystation account ID that initiated the transaction | integer | 123456 |
RequestIP | Request ip | The ip used in the initiation of the request | string | 192.168.1.1 |
RequestUserAgent | Request user agent | String that identifies the application client that initiated the transaction request | string | Mozilla/5.0 |
RequestHttpReferrer | Request http referrer | HTTP referrer header if applicable to original transaction request | string value | https://www.example.com |
PaymentRequestTime | Payment request time | The time the transaction was initiated at | datetime | 2017-01-13 09:38:26 |
DigitalOrderTime | Digital order time | Timestamp the transaction URL was created (does not apply to 2-party transactions) | datetime | 2018-03-11 02:40:16 |
DigitalReceiptTime | Digital receipt time | Timestamp the transaction response was received by the card switch | datetime | 2018-03-11 02:40:16 |
PaystationTransactionID | Paystation transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
FuturePaymentToken | Future payment token | A unique identification token assigned to each saved credit card | string | abc123efg456 |
FuturePaymentPanGuid | Future payment pan GUID | A unique id associated with card | ||
FuturePaymentPanExpGuid | Future payment pan exp GUID | A unique id associated with this cards expiry date | ||
IssuerName | Issuer name | The card issuing institution if known | string value | KIWIBANK LIMITED |
IssuerCountry | Issuer country | The country the card was issued if known | string value | NEW ZEALAND |
Token bill + auth
Authorise an amount against a stored token. You can find out more about authorisations here.
2 party
Example Request
POST https://www.paystation.co.nz/direct/paystation.dll
POST body parameters
paystation=_empty
&pstn_nr=t
&pstn_pi=123456
&pstn_gi=PAYSTATION
&pstn_ms=abcd-defg-hijk
&pstn_am=5000
&pstn_2p=t
&pstn_fp=t
&pstn_pa=t
&pstn_ft=17m3tf56z3j9w171784id6vn92232ry4x2qvkh2bk9s7ww0y85bv3mm17109o66c
The above request returns on SUCCESS an XML response structured like this:
<?xml version="1.0" standalone="yes"?>
<PaystationFuturePaymentResponse>
<FuturePaymentToken>17m3tf56z3j9w171784id6vn92232ry4x2qvkh2bk9s7ww0y85bv3mm17109o66c</FuturePaymentToken>
<FuturePaymentPanGuid>{19B950BB-0C8E-465B-9286-000057EC3E9E}</FuturePaymentPanGuid>
<FuturePaymentPanExpGuid>{FF9551A7-3674-46E3-ABC2-000057EC5C21}</FuturePaymentPanExpGuid>
<ec>0</ec>
<em>Transaction successful</em>
<ti>0085901911-01</ti>
<ct>mastercard</ct>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085901911-01</TransactionID>
<PurchaseAmount>5000</PurchaseAmount>
<SurchargeAmount/>
<Locale/>
<ReturnReceiptNumber>85901911</ReturnReceiptNumber>
<ShoppingTransactionNumber/>
<AcqResponseCode>00</AcqResponseCode>
<QSIResponseCode>0</QSIResponseCode>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 10:27:00</TransactionTime>
<PaystationErrorCode>0</PaystationErrorCode>
<PaystationErrorMessage>Transaction successful</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<CardNo>555555XXXXXXX444</CardNo>
<CardExpiry>1705</CardExpiry>
<TransactionProcess>authorisation</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber>0116</BatchNumber>
<AuthorizeID/>
<Cardtype>MC</Cardtype>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 10:27:00</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime>2017-01-16 10:27:00</DigitalReceiptTime>
<PaystationTransactionID>0085901911-01</PaystationTransactionID>
<FuturePaymentToken>17m3tf56z3j9w171784id6vn92232ry4x2qvkh2bk9s7ww0y85bv3mm17109o66c</FuturePaymentToken>
<FuturePaymentPanGuid>{19B950BB-0C8E-465B-9286-000057EC3E9E}</FuturePaymentPanGuid>
<FuturePaymentPanExpGuid>{FF9551A7-3674-46E3-ABC2-000057EC5C21}</FuturePaymentPanExpGuid>
<IssuerName>unknown</IssuerName>
<IssuerCountry>unknown</IssuerCountry>
</PaystationFuturePaymentResponse>
The above request returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<PaystationFuturePaymentResponse>
<ec>13</ec>
<em>Transaction already in progress</em>
<ti>0085900404-01</ti>
<ct/>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085900404-01</TransactionID>
<PurchaseAmount>0</PurchaseAmount>
<SurchargeAmount/>
<Locale>en</Locale>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 09:53:16</TransactionTime>
<PaystationErrorCode>13</PaystationErrorCode>
<PaystationErrorMessage>Transaction already in progress</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>purchase</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype/>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 09:53:16</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime/>
<PaystationTransactionID/>
</PaystationFuturePaymentResponse>
This endpoint is used for performing an authorisation on a stored token.
HTTP Request
POST https://www.paystation.co.nz/direct/paystation.dll
Required POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
paystation | Transaction initiator flag | Required for payment engine | _empty | |
pstn_nr | No Redirect flag | Required for payment engine | T | |
pstn_pi | Paystation ID | The Paystation ID or Alternative Paystation ID | 612345 | |
pstn_gi | Gateway ID | The Gateway ID | PAYSTATION | |
pstn_ms | Merchant Session ID | A unique identifier for every transaction attempt | qwertyuiop1234567890 | |
pstn_am | Amount | Transaction amount (default is cents) | 4200 | |
pstn_2p | Two party flag | Required for 2-party transactions | T | |
pstn_fp | Token transaction flag | Required for all token transactions except independent token refunds | T | |
pstn_ft | Token ID | A unique identifier that credit card details will be stored against (Paystation will provide one if none is provided) | qwertyuiop1234567890 | |
pstn_pa | Authorisation Flag | Required for authorisation transactions | T |
Optional POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_cu | Currency | Currency the transaction will be created in | USD | |
pstn_tm | Test Mode | Used to create a transaction in test mode | T | |
pstn_mr | Merchant reference | A non-unique identifier that can be assigned to a transaction | Cool Stories | |
pstn_af | Amount format | Defines the format of the amount | dollars.cents | |
pstn_mc | Customer details | A non-unique identifier that can be assigned to a transaction | abc123 | |
pstn_mo | Order details | Credit/debit card number (13 - 19 characters) | Dumplings | |
pstn_cc | Card security code | Three/Four digit code found on back of credit/debit card | 100 | |
pstn_fr | Reseller flag | Allows an account to make a transaction using the token from another account (requires admin configuration) | T | |
pstn_rf | Return format | Defines the response format from Paystation (default is XML) | JSON |
Optional query string parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_HMACTimestamp | HMAC Timestamp | The timestamp generated immediately before the request is generated | integer | 1481496738 |
pstn_HMAC | HMAC Hash | A hash of the request, the HMAC timestamp and the HMAC key | string | abc12345 |
Token update
A token update allows you to update the details of a stored token. This can be anything from adding a new expiry date, to changing the card number completely.
2 party
Example request
POST https://www.paystation.co.nz/direct/paystation.dll
POST body parameters
paystation=_empty
&pstn_nr=t
&pstn_pi=123456
&pstn_gi=PAYSTATION
&pstn_ms=abcd-defg-hijk
&pstn_2p=t
&pstn_fp=t
&pstn_cn=5555555555554444
&pstn_ex=1705
&pstn_fu=t
&pstn_ft=17m3tf56z3j9w171784id6vn92232ry4x2qvkh2bk9s7ww0y85bv3mm17109o66c
This endpoint is used for updating a stored token, this is a 2 party transaction only
HTTP request
POST https://www.paystation.co.nz/direct/paystation.dll
Required POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
paystation | Transaction initiator flag | Required for payment engine | String value | _empty |
pstn_nr | No Redirect flag | Required for payment engine | Single character "t" or "T" | T |
pstn_pi | Paystation ID | The Paystation ID | String value | 612345 |
pstn_gi | Gateway ID | The Gateway ID | String value | PAYSTATION |
pstn_ms | Merchant Session ID | A unique identifier for every transaction attempt | String value (max 64 chars) | qwertyuiop1234567890 |
pstn_2p | Two party flag | Required for 2-party transactions | Single character "t" or "T" | T |
pstn_fp | Token transaction flag | Required for all token transactions (except independent token refunds) | Single character "t" or "T" | T |
pstn_ft | Token name | A unique identifier that credit card details will be stored against (Paystation will generate one if none is provided) | String value (max 64 chars) | qwertyuiop1234567890is provided) |
pstn_cn | Card number | Credit/debit card number (13 - 19 characters) | Integer, no spaces in between card numbers | 5555555555554444 |
pstn_ex | Card expiry date | Four character expiry date | Integer, no spaces in between year and month (default is yymm format) | 1705 |
pstn_fu | Token update flag | Required for token update transactions | Single character "t" or "T" | T |
Optional POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_mr | Merchant reference | A non-unique identifier that can be assigned to a transaction | Cool Stories | |
pstn_mc | Customer details | A non-unique identifier that can be assigned to a transaction | abc123 | |
pstn_mo | Order details | Credit/debit card number (13 - 19 characters) | Dumplings | |
pstn_cc | Card security code | Three/Four digit code found on back of credit/debit card | 100 | |
pstn_HMACTimestamp | HMAC Timestamp | The timestamp generated immediately before the request is generated | integer | 1481496738 |
pstn_HMAC | HMAC Hash | A hash of the request, the HMAC timestamp and the HMAC key | string | abc12345 |
pstn_fr | Reseller flag | Allows an account to make a transaction using the token from another account (requires admin configuration) | T | |
pstn_rf | Return format | Defines the response format from Paystation (default is XML) | JSON |
Optional query string parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_HMACTimestamp | HMAC Timestamp | The timestamp generated immediately before the request is generated | integer | 1481496738 |
pstn_HMAC | HMAC Hash | A hash of the request, the HMAC timestamp and the HMAC key | string | abc12345 |
Return response
The above request returns on SUCCESS an XML response structured like this:
<?xml version="1.0" standalone="yes"?>
<PaystationFuturePaymentResponse>
<ec>34</ec>
<em>Future Payment Saved Ok</em>
<ti>0085902164-01</ti>
<ct>mastercard</ct>
<merchant_ref/>
<tm>P</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085902164-01</TransactionID>
<PurchaseAmount>0</PurchaseAmount>
<SurchargeAmount/>
<Locale>en</Locale>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 10:31:45</TransactionTime>
<PaystationErrorCode>34</PaystationErrorCode>
<PaystationErrorMessage>Future Payment Saved Ok</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>purchase</TransactionProcess>
<TransactionMode>P</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype>MC</Cardtype>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 10:31:45</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime>2017-01-16 10:31:45</DigitalReceiptTime>
<PaystationTransactionID>0085902164-01</PaystationTransactionID>
<FuturePaymentToken>72n0169hpd5uc43iwk401b8195jz4h0p22q64p953bpq6w2b25xxewp4l3sz9hu5</FuturePaymentToken>
<FuturePaymentPanGuid>{19B950BB-0C8E-465B-9286-000057EC3E9E}</FuturePaymentPanGuid>
<FuturePaymentPanExpGuid>{FF9551A7-3674-46E3-ABC2-000057EC5C21}</FuturePaymentPanExpGuid>
<IssuerName>unknown</IssuerName>
<IssuerCountry>unknown</IssuerCountry>
</PaystationFuturePaymentResponse>
The above request returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<PaystationFuturePaymentResponse>
<ec>13</ec>
<em>Transaction already in progress</em>
<ti>0085900404-01</ti>
<ct/>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085900404-01</TransactionID>
<PurchaseAmount>0</PurchaseAmount>
<SurchargeAmount/>
<Locale>en</Locale>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 09:53:16</TransactionTime>
<PaystationErrorCode>13</PaystationErrorCode>
<PaystationErrorMessage>Transaction already in progress</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>purchase</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype/>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 09:53:16</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime/>
<PaystationTransactionID/>
</PaystationFuturePaymentResponse>
Attribute | Name | Description | Type | Example |
---|---|---|---|---|
ec | Error code | The error code status of the transaction | integer | 1 |
em | Error message | The error message status of the transaction | string | Transaction successful |
ti | Transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
ct | Card type | The card issuer | string | mastercard |
merchant_ref | A non-unique identifier that can be assigned to a transaction | string | abc123 | |
tm | Test mode | Denotes if the transaction was completed in test mode or not | string | t |
MerchantSession | Merchant Session ID | A unique value to identify a transaction by | string | abcd-defg-hijk |
UsedAcquirerMerchantID | ||||
TransactionID | Transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
PurchaseAmount | Purchase amount | A positive integer in cent value or alternatively the option specified in the transaction representing the charged amount | positive integer or zero | 5000 |
SurchargeAmount | ||||
Locale | Locale | The language tag represents the language the response text is provided in | string value | en |
ReturnReceiptNumber | Return receipt number | The RRN number is a virtual terminal counter for the transaction and is not unique | Integer | 85793423 |
ShoppingTransactionNumber | Shopping transaction number | Is a unique number relating to the Transaction ID (eGate integration's only) | Integer | 85793423 |
AcqResponseCode | Acq response code | Transaction response code from the acquiring bank | Integer | 00 |
QSIResponseCode | QSI response code | Issuing bank response code – the actual raw result from the payment server. Please process transaction result from the PaystationErrorCode | Integer | 0 |
CSCResultCode | CSC result code | The response code in response to verifying the card security code if applicable to transaction | Single Character | "M" |
AVSResultCode | AVS result code | Result of any AVS validation. Not supported in New Zealand | Empty | |
TransactionTime | Transaction time | The time the transaction was completed | datetime | 2017-01-13 09:38:26 |
PaystationErrorCode | Error code | The error code status of the transaction | integer | 1 |
PaystationErrorMessage | Error message | The error message status of the transaction | string | Transaction successful |
PaystationExtendedErrorMessage | Extended error message | Extra information regarding the error code if applicable | string value | Refer to card issuer |
MerchantReference | Merchant reference | A non-unique identifier that can be assigned to a transaction | string | abc123 |
CardNo | Card number | A masked card number of the card that completed the transaction | string | 555555XXXXXXX444 |
CardExpiry | Card expiry date | The expiry of the card that completed the transaction | date YYMM | 1705 |
TransactionProcess | Transaction process | The transaction method identification | string | purchase |
TransactionMode | Transaction mode | T or P represents the transaction is a test (T) or production (P) transaction | string value | T |
BatchNumber | Batch number | A four digit number representing the expected settlement date of the transaction in the format MMDD | datemonth | 0518 |
AuthorizeID | Authorize ID | A unique reference provided by the bank to trace the transaction | string value | R81194 |
Cardtype | Card type | The card issuer | string | MC |
Username | Paystation account ID | The Paystation account ID that initiated the transaction | integer | 123456 |
RequestIP | Request ip | The ip used in the initiation of the request | string | 192.168.1.1 |
RequestUserAgent | Request user agent | String that identifies the application client that initiated the transaction request | string | Mozilla/5.0 |
RequestHttpReferrer | Request http referrer | HTTP referrer header if applicable to original transaction request | string value | https://www.example.com |
PaymentRequestTime | Payment request time | The time the transaction was initiated at | datetime | 2017-01-13 09:38:26 |
DigitalOrderTime | Digital order time | Timestamp the transaction URL was created (does not apply to 2-party transactions) | datetime | 2018-03-11 02:40:16 |
DigitalReceiptTime | Digital receipt time | Timestamp the transaction response was received by the card switch | datetime | 2018-03-11 02:40:16 |
PaystationTransactionID | Paystation transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
FuturePaymentToken | Future payment token | A unique identification token assigned to each saved credit card | string | abc123efg456 |
FuturePaymentPanGuid | Future payment pan GUID | A unique id associated with card | ||
FuturePaymentPanExpGuid | Future payment pan exp GUID | A unique id associated with this cards expiry date | ||
IssuerName | Issuer name | The card issuing institution if known | string value | KIWIBANK LIMITED |
IssuerCountry | Issuer country | The country the card was issued if known | string value | NEW ZEALAND |
Token delete
A token delete allows you to delete a token that is no longer required.
2 party
Example request
POST https://www.paystation.co.nz/direct/paystation.dll
POST body parameters
paystation=_empty
&pstn_nr=t
&pstn_pi=123456
&pstn_gi=PAYSTATION
&pstn_ms=abcd-defg-hijk
&pstn_2p=t
&pstn_fp=t
&pstn_ft=17m3tf56z3j9w171784id6vn92232ry4x2qvkh2bk9s7ww0y85bv3mm17109o66c
&pstn_fx=t
This endpoint is used for deleting a stored token, this is a 2 party transaction only
HTTP request
POST https://www.paystation.co.nz/direct/paystation.dll
Required POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
paystation | Transaction initiator flag | Required for payment engine | String value | _empty |
pstn_nr | No Redirect flag | Required for payment engine | Single character "t" or "T" | T |
pstn_pi | Paystation ID | The Paystation ID | String value | 612345 |
pstn_gi | Gateway ID | The Gateway ID | String value | PAYSTATION |
pstn_ms | Merchant Session ID | A unique identifier for every transaction attempt | String value (max 64 chars) | qwertyuiop1234567890 |
pstn_2p | Two party flag | Required for 2-party transactions | Single character "t" or "T" | T |
pstn_fp | Token transaction flag | Required for all token transactions (except independent token refunds) | Single character "t" or "T" | T |
pstn_ft | Token name | A unique identifier that credit card details will be stored against (Paystation will generate one if none is provided) | String value (max 64 chars) | qwertyuiop1234567890 |
pstn_fx | Token delete flag | Required for token delete transactions | Single character "t" or "T" | T |
Optional POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_mr | Merchant reference | A non-unique identifier that can be assigned to a transaction | String value (max 64 chars) | abc123 |
pstn_mc | Customer details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_mo | Order details | A non-unique identifier that can be assigned to a transaction | String value (max 255 chars) | abc123 |
pstn_cc | Card security code | Three/Four digit code found on back of credit/debit card | String value | 100 |
pstn_fr | Reseller flag | Allows an account to make a transaction using the token from another account | Single character "t" or "T" | T |
pstn_rf | Return format | Defines the response format from Paystation (default is XML) | String value | JSON |
Optional query string parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_HMACTimestamp | HMAC Timestamp | The timestamp generated immediately before the request is generated | integer | 1481496738 |
pstn_HMAC | HMAC Hash | A hash of the request, the HMAC timestamp and the HMAC key | string | abc12345 |
Return response
The above request returns on SUCCESS an XML response structured like this:
<?xml version="1.0" standalone="yes"?>
<response>
<ec>34</ec>
<em>Future Payment Saved Ok</em>
<ti>0085902014-01</ti>
<ct/>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085902014-01</TransactionID>
<PurchaseAmount/>
<SurchargeAmount/>
<Locale/>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 10:29:10</TransactionTime>
<PaystationErrorCode>34</PaystationErrorCode>
<PaystationErrorMessage>Future Payment Saved Ok</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>token</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype/>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 10:29:10</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime>2017-01-16 10:29:10</DigitalReceiptTime>
<PaystationTransactionID>0085902014-01</PaystationTransactionID>
</response>
The above request returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version="1.0" standalone="yes"?>
<response>
<ec>31</ec>
<em>Future Payment Token not loaded</em>
<ti>0085902037-01</ti>
<ct/>
<merchant_ref/>
<tm>T</tm>
<MerchantSession>abcd-defg-hijk</MerchantSession>
<UsedAcquirerMerchantID/>
<TransactionID>0085902037-01</TransactionID>
<PurchaseAmount/>
<SurchargeAmount/>
<Locale/>
<ReturnReceiptNumber/>
<ShoppingTransactionNumber/>
<AcqResponseCode/>
<QSIResponseCode/>
<CSCResultCode/>
<AVSResultCode/>
<TransactionTime>2017-01-16 10:29:33</TransactionTime>
<PaystationErrorCode>31</PaystationErrorCode>
<PaystationErrorMessage>Future Payment Token not loaded</PaystationErrorMessage>
<PaystationExtendedErrorMessage/>
<MerchantReference/>
<TransactionProcess>token</TransactionProcess>
<TransactionMode>T</TransactionMode>
<BatchNumber/>
<AuthorizeID/>
<Cardtype/>
<Username>123456</Username>
<RequestIP>192.168.1.1</RequestIP>
<RequestUserAgent>Mozilla/5.0 (Windows NT 10.0; WOW64)</RequestUserAgent>
<RequestHttpReferrer/>
<PaymentRequestTime>2017-01-16 10:29:33</PaymentRequestTime>
<DigitalOrderTime/>
<DigitalReceiptTime>2017-01-16 10:29:33</DigitalReceiptTime>
<PaystationTransactionID>0085902037-01</PaystationTransactionID>
</response>
Attribute | Name | Description | Type | Example |
---|---|---|---|---|
ec | Error code | The error code status of the transaction | integer | 1 |
em | Error message | The error message status of the transaction | string | Transaction successful |
ti | Transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
ct | Card type | The card issuer | string | mastercard |
merchant_ref | A non-unique identifier that can be assigned to a transaction | string | abc123 | |
tm | Test mode | Denotes if the transaction was completed in test mode or not | string | t |
MerchantSession | Merchant Session ID | A unique value to identify a transaction by | string | abcd-defg-hijk |
UsedAcquirerMerchantID | ||||
TransactionID | Transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
PurchaseAmount | Purchase amount | A positive integer in cent value or alternatively the option specified in the transaction representing the charged amount | positive integer or zero | 5000 |
SurchargeAmount | ||||
Locale | Locale | The language tag represents the language the response text is provided in | string value | en |
ReturnReceiptNumber | Return receipt number | The RRN number is a virtual terminal counter for the transaction and is not unique | Integer | 85793423 |
ShoppingTransactionNumber | Shopping transaction number | Is a unique number relating to the Transaction ID (eGate integration's only) | Integer | 85793423 |
AcqResponseCode | Acq response code | Transaction response code from the acquiring bank | Integer | 00 |
QSIResponseCode | QSI response code | Issuing bank response code – the actual raw result from the payment server. Please process transaction result from the PaystationErrorCode | Integer | 0 |
CSCResultCode | CSC result code | The response code in response to verifying the card security code if applicable to transaction | Single Character | "M" |
AVSResultCode | AVS result code | Result of any AVS validation. Not supported in New Zealand | Empty | |
TransactionTime | Transaction time | The time the transaction was completed | datetime | 2017-01-13 09:38:26 |
PaystationErrorCode | Error code | The error code status of the transaction | integer | 1 |
PaystationErrorMessage | Error message | The error message status of the transaction | string | Transaction successful |
PaystationExtendedErrorMessage | Extended error message | Extra information regarding the error code if applicable | string value | Refer to the card issuer |
MerchantReference | Merchant reference | A non-unique identifier that can be assigned to a transaction | string | abc123 |
CardNo | Card number | A masked card number of the card that completed the transaction | string | 555555XXXXXXX444 |
CardExpiry | Card expiry date | The expiry of the card that completed the transaction | date YYMM | 1705 |
TransactionProcess | Transaction process | The transaction method identification | string | purchase |
TransactionMode | Transaction mode | T or P represents the transaction is a test (T) or production (P) transaction | string value | T |
BatchNumber | Batch number | A four digit number representing the expected settlement date of the transaction in the format MMDD | date MMDD | 0518 |
AuthorizeID | Authorize ID | A unique reference provided by the bank to trace the transaction | string value | R81194 |
Cardtype | Card type | The card issuer | string | MC |
Username | Paystation account ID | The Paystation account ID that initiated the transaction | integer | 123456 |
RequestIP | Request ip | The ip used in the initiation of the request | string | 192.168.1.1 |
RequestUserAgent | Request user agent | String that identifies the application client that initiated the transaction request | string | Mozilla/5.0 |
RequestHttpReferrer | Request http referrer | HTTP referrer header if applicable to original transaction request | string value | https://www.example.com |
PaymentRequestTime | Payment request time | The time the transaction was initiated at | datetime | 2017-01-13 09:38:26 |
DigitalOrderTime | Digital order time | Timestamp the transaction URL was created (does not apply to 2-party transactions) | datetime | 2018-03-11 02:40:16 |
DigitalReceiptTime | Digital receipt time | Timestamp the transaction response was received by the card switch | datetime | 2018-03-11 02:40:16 |
PaystationTransactionID | Paystation transaction ID | A unique value applied to all transactions | string | 0123456789-01 |
Validation
Paystation can validate an API request using either IP limiting or HMAC authentication.
IP limiting
Paystation offer IP limiting. To whitelist an IP address contact Paystation and quote the required account ID and the relevant IP details.
HMAC authentication
There are two methods Paystation uses to securely authenticate server requests in our system: IP limiting and HMAC authentication. Paystation uses HMAC authentication as an alternative to IP limiting where required, and it can be used to implement the Dynamic URL API.
In cryptography, a keyed-hash message authentication code (HMAC) is a specific construction for calculating a message authentication code (MAC) involving a cryptographic hash function in combination with a secret cryptographic key. As with any MAC, it may be used to simultaneously verify both the data integrity and the authentication of a message.
We generate the HMAC authentication key used to hash your data within the Paystation system and pass this to you to use during your requests.
We currently support HMAC authentication on the following interfaces:
- Payment Processor
- Reporting System
- Quick Lookup
- BIN Lookup
To use HMAC authentication you need to append two extra variables to the URL/GET query string that you are using to initiate a transaction or lookup. This assumes that you are passing all other parameters in the request body as standard POST key/value pairs.
pstn_HMACTimestamp is a unix timestamp that you will need to generate right before you calculate the HMAC and send us the transaction. This value is used during HMAC calculation
pstn_HMAC is the HMAC hash of a concatenation of 3 byte mapped values, the timestamp, the string ‘paystation’, and the POST request body. This is generated using the SHA512 cryptographic algorithm and the HMAC authentication key provided by Paystation.
string to hash = byte array of timestamp (integer/string) + byte array of 'paystation' (string) +
byte array of request body (string)
Reporting and Lookups
Use our Reporting API to obtain transaction data and our BIN lookup API to check a card's BIN number against our database.
Transaction reporting
Example request
POST https://payments.paystation.co.nz/reporting/ if using HMAC: POST https://payments.paystation.co.nz/reporting/?hmac=af9dcec07d0fa4f451afd37357140c9fe34eebeadd76b1570eac864d5cdf22a86f85c2055127c60b075344b313b58c46cd74162923406549b0239bf06051ef59&time=1596591645339
POST headers
Content-Type: application/x-www-form-urlencoded
POST body parameters
pstn_pi=123456
&pstn_gi=519163
Reporting queries are initiated via an HTTPS POST request to a Paystation Reporting URL, with the response sent directly back as either an XML formatted response (default) or a JSON formatted response which includes the transaction details.
HTTP request
POST https://payments.paystation.co.nz/reporting/
Required POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_pi | Paystation ID | The Paystation ID | String value | 612345 |
pstn_gi | Gateway ID | The Gateway ID | String value | PAYSTATION |
Optional POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_cu | Currency | Requests transactions processed in a particular currency | String value (3 chars) | USD |
pstn_rf | Return format | Defines the response format from Paystation | String value, "XML", "JSON" | JSON |
currency_list | Currency list | Requests transactions processed in a list of currencies | String value (min 3 chars) | NZD,USD,AUD |
from_date | From date | Requests transactions processed after this date | String value (10 chars, YYYY-MM-DD format) | 2017-04-20 |
to_date | To date | Requests transactions processed before this date | String value (10 chars, YYYY-MM-DD format) | 2017-04-25 |
from_time | From time | Requests transactions processed after this time | String value (8 chars, HH:MM:SS format) | 12:34:56 |
to_time | To time | Requests transactions processed before this time | String value (8 chars, HH:MM:SS format) | 12:56:34 |
settlement_date | Settlement date | Determines whether the date range should be interpreted as settlement dates rather than transaction dates | Single character "Y" for yes or "N" for no | Y |
merchant_session | Merchant session ID | Requests transactions that match the merchant session ID exactly | String value (max 64 chars) | qwertyuiop1234567890 |
merchant_session_partial_match | Merchant session ID partial match | Determines whether the merchant session ID needs to match exactly | Single character "Y" for yes or "N" for no | Y |
transaction_id | Transaction ID | Requests transactions that match the transaction ID exactly | String value (13 chars) | 0012345678-01 |
Transaction_id_partial_match | Transaction ID partial match | Determines whether the transaction ID needs to match exactly | Single character "Y" for yes or "N" for no | Y |
merchant_reference | Requests transactions that match the merchant reference exactly | String value (max 64 chars) | abc123 | |
merchant_reference_partial_match | Determines whether the merchant reference needs to match exactly | Single character "Y" for yes or "N" for no | Y | |
amount | Amount | Requests transactions determined by this amount and the amount_type set | Integer (denominated in currency units) | 4200 |
amount_type | Amount type | Requests transactions determined by this amount_type and the amount set | String value, "LESS", "GREATER" or "EXACT" | EXACT |
card_start | Card start numbers | Requests transactions with card numbers that match the first six numbers (must be used in conjunction with card_end) | Integer (6 chars) | 512345 |
card_end | Card end numbers | Requests transactions with card numbers that match the last three numbers (must be used in conjunction with card_start) | Integer (3 chars) | 789 |
token | Token name | Requests transactions that match the token name exactly | String value (max 64 chars) | qwertyuiop1234567890 |
transaction_mode | Transaction mode | Requests transactions that match the transaction mode | Single character "P" for production or "T" for test | P |
transaction_type | Transaction type | Requests transactions that match the transaction type | String value, "PURCHASE", "REFUND", "AUTHORISATION", "CAPTURE", "TOKEN" | PURCHASE |
refund_format | Refund amount format | Determines whether the amount for refund transactions is returned as positive or negative | String value, "POSITIVE", "NEGATIVE" | NEGATIVE |
returned_result_code | Paystation error code | Requests transactions that match an error code or type | String value, "SUCCESSFUL", "FAILED", "INCOMPLETE", the error code | SUCCESSFUL |
payme_order_id | PayMe order ID | Requests transactions that relate to the PayMe order ID exactly | Integer (5 chars) | 13872 |
limit | Limit results | Determines the limit of how many transactions can be returned | Integer | 100 |
limit_sort | Limit sort | Determines which order the transactions will be returned | String value, "ASC" for ascending, "DESC" for descending | ASC |
start_record | Start record | Determines the starting point of transactions to be returned (must be used in conjunction with limit) | Integer | 5 |
include_total | Include total | Determines whether the parameter total_transaction_count will be included (will provide the total count regardless of the limit set) | Single character "Y" for yes or "N" for no | Y |
total_only | Total only | Determines whether to only request the parameter total_transaction_count | Single character "Y" for yes or "N" for no | Y |
short_tags | Short tags | Determines whether the return results will use short tags (useful for mobile development) | Single character "Y" for yes or "N" for no | Y |
Optional query string parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_HMACTimestamp | HMAC Timestamp | The timestamp generated immediately before the request is generated | integer | 1481496738 |
pstn_HMAC | HMAC Hash | A hash of the request, the HMAC timestamp and the HMAC key | string | abc12345 |
HTTP response
The above command returns on SUCCESS an XML response structured like this:
<?xml version='1.0' ?>
<PaystationReporting>
<LookupStatus>
<LookupCode>00</LookupCode>
<LookupMessage>Successful</LookupMessage>
<RemoteHostAddress>192.168.1.1</RemoteHostAddress>
</LookupStatus>
<transaction_count>1</transaction_count>
<transactions>
<transaction>
<paystationId>123456</paystationId>
<gatewayId>PAYSTATION</gatewayId>
<transactionId>0073478727-01</transactionId>
<time>2016-06-14 13:30:13</time>
<transactionType>purchase</transactionType>
<amount>1000</amount>
<surchargeAmount />
<currency>NZD</currency>
<merchantReference>paystation</merchantReference>
<merchantSession>1465867813-13hL7klL</merchantSession>
<transactionMode>T</transactionMode>
<batchNumber />
<receiptNumber />
<authorizeId />
<cardType />
<maskedCardNumber />
<totalSuccessfulRefunds>0</totalSuccessfulRefunds>
<totalSuccessfulCaptures>0</totalSuccessfulCaptures>
<futurePaymentToken />
<errorCode />
<errorMessage>Incomplete</errorMessage>
</transaction>
</transactions>
</PaystationReporting>
The above command returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version='1.0' ?>
<PaystationReporting>
<LookupStatus>
<LookupCode>03</LookupCode>
<LookupMessage>Access denied for account [123456]</LookupMessage>
<RemoteHostAddress>192.168.1.1</RemoteHostAddress>
</LookupStatus>
</PaystationReporting>
The response is sent in the form of an XML packet. It starts with a LookupStatus
indicating whether your request was successfully received/processed, and then includes (optionally) the transaction_count
element and the transactions
element which includes one or more transaction
elements. You will be able to extract the response values using the standard tools available within your development environment.
Attribute | Name | Description | Type | Example |
---|---|---|---|---|
paystationId | Paystation ID | The Paystation ID or Alternative Paystation ID | integer | 612345 |
gatewayId | Gateway ID | The Gateway ID | string | PAYSTATION |
transactionId | Transaction ID | Unique transaction ID given by Paystation | string | 030201001-01 |
time | Time | time of transaction initiation in our system, YYYY-MM-DD HH:NN:SS | datetime | 2017-01-13 09:38:26 |
transactionType | Transaction Type | The type of transaction | string | purchase |
amount | Amount | Amount of transaction in base currency units (cents) | positive integer | 100 |
currency | Currency | Currency the transaction was created in | currency | USD |
merchantReference | Merchant Reference | A non-unique identifier that may have been assigned to the transaction | string | Cool Stories |
merchantSession | Merchant Session | A unique identifier that was assigned to the transaction | string | qwertyuiop1234567890 |
transactionMode | Transaction Mode | The transaction mode the transaction was initiated with | string | T |
batchNumber | Batch Number | A label assigned to a transaction by the bank indicating which batch of transactions the transaction will be settled into the merchants account with. This can be in several formats depending on bank, but usually indicates the date of the settlement batch | integer | 0812 |
receiptNumber | Receipt Number | A number returned by the bank or our systems depending on processing type. This should be unique per merchant facility | integer | 010000 |
authorizeId | Authorize ID | A string returned by the bank indicating processing type | integer | 112313 |
cardType | Card type | This will be populated if the BIN matches our internal algorithms | string | MASTERCARD |
maskedCardNumber | Masked Card Number | Card number masked according to accounting settings, usually displaying first 6 and last 3 digits | string | 555555XXXXXXX444 |
totalSuccessfulRefunds | Total Successful Refunds | The amount (if any) of this transaction that has been subsequently refunded in base currency units | positive integer | 1000 |
totalSuccessfulCaptures | Total Successful Captures | The amount (if any) of this transaction that has been subsequently captured in base currency units. This field would only be relevant to transactions with a transactionType of ‘authorisation’ | integer | 5000 |
futurePaymentToken | Future Payment Token | The token that was created/used (if any) during this transaction | string | abcd123 |
errorCode | Error Code | The status of this transaction | integer | 0 |
errorMessage | Error Message | The description status of this transaction | string | Transactions successful |
Errors
A Transaction reporting response XML packet is broken down into two separate xml element groups, the LookupStatus
and the BinResult
LookupStatus errors
The LookupStatus
holds the data depending on wherever the actual request for the Lookup was successfully
Through the LookupCode
and LookupMessage
xml elements of a LookupStatus
you will obtain an error code that corresponds to the below link
The LookupStatus
error's are all standard lookup errors found here
Transaction errors
The transaction
holds the data depending on the outcome of the transaction found.
The transaction
error's are all standard transaction errors found here
BIN lookup
Example request
POST https://payments.paystation.co.nz/bin/
POST headers
Content-Type: application/x-www-form-urlencoded
POST body parameters
pstn_pi=123456
&pstn_bi=519163
BIN lookup queries are initiated via an HTTPS POST request to a Paystation Lookup URL, with the response sent directly back as either an XML formatted response (default) or a JSON formatted response which includes the BIN / IIN details
HTTP request
POST https://payments.paystation.co.nz/bin/
Required POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_pi | Paystation ID | The Paystation ID | String value | 612345 |
pstn_bi | BIN Number | BIN. The first 6 digits of a credit card number | 519163 |
Optional POST body parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_rf | Return format | Defines the response format from Paystation (default is XML) | String value | JSON |
Optional query string parameters
Parameter | Name | Description | Value | Example |
---|---|---|---|---|
pstn_HMACTimestamp | HMAC Timestamp | The timestamp generated immediately before the request is generated | integer | 1481496738 |
pstn_HMAC | HMAC Hash | A hash of the request, the HMAC timestamp and the HMAC key | string | abc12345 |
HTTP response
The above command returns on SUCCESS an XML response structured like this:
<?xml version='1.0' ?>
<PaystationBinLookup>
<LookupStatus>
<LookupCode>00</LookupCode>
<LookupMessage>Successful</LookupMessage>
<RemoteHostAddress></RemoteHostAddress>
</LookupStatus>
<BinResult>
<bin>519163</bin>
<issuer>KIWIBANK LIMITED</issuer>
<country>NEW ZEALAND</country>
<cardType>MASTERCARD</cardType>
<cardSubType />
<classification>Classic / Gold</classification>
</BinResult>
</PaystationBinLookup>
The above command returns on FAILURE an XML response structured like this (The error code/message will vary depending on the resulting failure):
The error message and code will vary depending on the error
<?xml version='1.0' ?>
<PaystationBinLookup>
<LookupStatus>
<LookupCode>03</LookupCode>
<LookupMessage>Access denied for account [123456]</LookupMessage>
<RemoteHostAddress>192.168.1.1</RemoteHostAddress>
</LookupStatus>
</PaystationBinLookup>
The response is sent in the form of an XML packet. It starts with a LookupStatus
indicating whether
your request was successfully received/processed, and then includes the BinResult
. You will be able
to extract the response values using the standard tools available within your development environment.
Attribute | Name | Description | Type | Example |
---|---|---|---|---|
bin | BIN Number | BIN. The first 6 digits of a credit card number | integer | 519163 |
issuer | Issuer name | The card issuing institution if known | string | KIWIBANK LIMITED |
country | Issuer country | The country that the card was issued in if known | string | NEW ZEALAND |
cardType | Card type | This will be populated if the BIN matches our internal algorithms | string | MASTERCARD |
cardSubType | Card sub type | Credit/Debit if known | string | Debit |
classification | Classification | Classification status of card | string | Platinum |
Errors
A BIN Lookup response XML packet is broken down into two separate xml element groups, the LookupStatus
and the BinResult
LookupStatus errors
The LookupStatus
holds the data depending on wherever the actual request for the Lookup was successfully
Through the LookupCode
and LookupMessage
xml elements of a LookupStatus
you will obtain an error code that corresponds to the below table
The LookupStatus
error's are all standard lookup errors found here
BinResult errors
The BinResult
holds the data depending on the outcome of the transaction found.
The BinResult
error's are all standard transaction errors found here
Payments Page
If you are a 3-party merchant, this is where your customers will complete their payment. You can view the live demo here.
Customisation and themes
You can use your own theme on our hosted payment page. The best way to do this, is to make a test payment to view the page, and use your browsers dev tools to try out your own CSS. You can email your CSS and logo (svg or png) to support.
Here are a few basic ideas for things you might want to change on the payment page. It is generally aimed at customising colours and styles as opposed to making layout changes.
Change the colours
Colours
:root {
--page-background-colour: #eee;
--form-background-colour: #fff;
--button-colour: #48546a;
--button-hover-colour: #ccd234;
--text-colour: #333;
--faded-text-colour: #777;
--input-background-colour: #fff;
--input-placeholder-colour: #333;
}
Tweaks
/* rounded edges on buttons and inputs */
.payment-button, .payment-type-button, input {
border-radius: 3px;
}
/* rounded edges on the form and error messages */
.transaction-result, .payment-wrapper {
border-radius: 5px;
}
/* make all buttons have solid backgrounds */
.payment-button, .payment-type-button {
background-color: var(--button-colour);
border-color: var(--button-colour);
color: #fff;
}
.payment-type-button:hover, .payment-type-button:active, .payment-type-button:focus,
.payment-button:hover, .payment-button:active, .payment-button:focus {
background-color: var(--button-hover-colour);
border-color: var(--button-hover-colour);
color: #fff;
}
/* style the inputs */
input {
border-radius: 0;
border: 2px solid #d2dbe1;
box-shadow: none;
background-color: #f0f; /* this is fine */
/* background: #f0f; */ /* this will override the background-image and remove icons inside the inputs */
}
/* hide the green bar from the top of your form */
.paystation-fold {
display: none;
}
/* override the gradient background on the amount box */
.payment-amount-box {
background-image: none;
padding: 16px 28px 0;
}
/* put a divider between the amount and the rest of the form */
.payment-amount-box::after {
border-bottom: dashed 1px rgba(255, 255, 255, 0.5);
display: block;
content: "";
margin: 12px 0 8px;
}
/* line your logo up with the rest of the form */
.merchant-logo-margin {
background-color: var(--form-background-colour);
margin: 0;
padding: 28px 28px 0;
}
/* link and heading colours */
.payment-back-link, .payment-subheading {
color: var(--text-colour);
}
.payment-back-link:hover {
color: #a1e9ff;
}
There are some css variables you can set to change the main colours
--page-background-colour
is for the area around the form.--form-background-colour
is for the form and error messages.--button-colour
is applied to primary and secondary buttons. (By default secondary buttons have a transparent background and a border, primary buttons have a solid background.)--button-hover-colour
replaces the default button when it is focused, hovered or active.--text-colour
is the base text colour used for the amount, inputs and errors.--faded-text-colour
is the secondary text colour used for the currency and payment type descriptions.--input-background-colour
is the background colour for an input that isn't active.--input-placeholder-colour
is the colour of the text seen inside inputs before a value is entered.
Framing the payment form
CSS
iframe.paystation-payment-frame {
border: none;
width: 100%;
min-height: 450px;
}
HTML
<iframe class="paystation-payment-frame" src="[payment_url]&b=[background_colour]"></iframe>
Dimensions Width: 300px to 500px. If the frame is wider than 500px it will center the form and display the pages background colour around it. Height: 350px to 450px. It depends on how many fields are displayed on your form. To avoid scrollbars, make a test transaction to see what it looks like.
Background colour
In order to make the form blend into your website, hide the iframe's border and set the payment page's background colour to match whatever your iframes parent element's background is.
You can change the background colour of the payment page (inside an iframe) by adding &b=[hex_colour] to the query string in the payment URL. This sets a new value for --page-background-colour
. In the PHP iFrame sample code it uses javascript to find the background colour of the iframe's parent and append it to the URL to help it blend into your page.
iFrame customisation
/* make the form background the same as the page background to remove the form's box appearance */
:root .iframe {
--page-background-colour: var(--form-background-colour);
}
/* remove the gradient background on the amount box */
.iframe .payment-amount-box {
background-image: none;
padding-top: 16px;
padding-bottom: 0;
}
/* put a border between the amount and the rest of the form */
.iframe .payment-amount-box::after {
border-bottom: solid 1px var(--faded-text-colour);
display: block;
content: "";
margin: 12px 0 0;
}
/* remove horizontal margins and padding from the form if you want to handle them in your own page */
.iframe .payment-amount-box, .iframe #payment-types-box, .iframe .payment-type-form {
margin-left: 0;
margin-right: 0;
padding-left: 0;
padding-right: 0;
}
/* have a box shadow if the user is not in an iframe */
.transaction-result, .payment-wrapper {
box-shadow: #000 5px 5px 25px;
}
/* hide the shadow if they are in an iframe so it doesn't get clipped by the iframe */
.iframe .transaction-result, .iframe .payment-wrapper {
box-shadow: none;
}
If the page is inside an iframe the .iframe
class gets added to the body element. Use this if you need iframes to be styled differently from users who are redirected to the payment page.
We hide our logo inside iframes to help them fit your theme. If you would like to include our logo somewhere on your site, you can get it here.
Often when using an iframe you just want to see the input fields and a button. You might want to try setting the form and background colour as the same colour to remove the box appearence, and hide the gradient background on the amount field. Here is an example.
Don't Give Us Dodgy CSS
Evil CSS
body {
background-image: url(https://external-site.com/image.jpg)
}
:root {
--faded-text-colour: var(--form-background-color)
}
/* customers must know when their card details are being saved */
#save_card_msg {
display: none;
}
/* in most cases this will prevent payments */
.card-security-code {
display: none;
}
Make sure there is good contrast between any text and the background. Talk to us if you want to hide any input fields (e.g. cardholder name) rather than doing it with css.
Our Logos
If you want to include our logo on your website you can use these SVGs.