| Environment | Base URL |
|---|---|
| Sandbox | https://proxy.payanywhere.dev |
| Production | https://proxy.payanywhere.com |
How To Start
- Sign up for a free North Developer account.
- Contact us for Sandbox credentials that can be used to try out this product in a test environment.
- Use the guide below or the Postman Collection to build your app. Resources to assist with development are provided here.
- When logged in, you can use the Integration Tracker to view the status of your integration, notes from meetings with Integration Engineers, resources related to your solution, and more by clicking the User profile icon in the top right corner of the screen and selecting Integrations.
- When development is complete, contact us to certify your integration. Once certified, the merchant or an authorized contact will be able to retrieve Production credentials from the API Access page of your Production Payments Hub account. For more information about using Payments Hub, visit the Help Center.
Server Requirements
Any connections must be made over TLS v1.2 or higher. The following are the supported ciphers:
- ECDHE-ECDSA-AES128-GCM-SHA256
- ECDHE-RSA-AES128-GCM-SHA256
- ECDHE-ECDSA-AES256-GCM-SHA384
- ECDHE-RSA-AES256-GCM-SHA384
Gateway Invoicing API Setup
Steps 1 and 2 are intended to be performed on your server. You may wish to encapsulate them so that your client-side code makes a single request for a payments URL providing order information.
1. Generate an auth token by calling a POST to the following request URL with the headers and payload below:
Method: POST
Request URL: https://proxy.payanywhere.com/auth
Headers:
| Name | Value | Description |
|---|---|---|
| Content-Type | application/json | Required. Content type of message. For most messages, this will be the default. |
| Content-Length | 1234 | Required. This value should be set to the exact length of the message body you are sending. |
| x-nabwss-appsource | pa_isv_1234567890abc | Required. This value is specific to each individual API account. For example, ISVs selling an application to multiple companies would use a different value for each company. Similarly, if a user has multiple accounts (MIDs) with us, the value for the x-nabwss-appsource header would be different for each MID. |
Request body:
JSON response:
2. Use the token and accountId received from the previous call to post a request for a hosted payments page.
Method: POST
Request URL: https://proxy.payanywhere.com/accounts/<ACCOUNT_ID>/invoices
Headers:
| Name | Value | Description |
|---|---|---|
| Content-Type | application/json | Required. Content type of message. For most messages, this will be the default. |
| Content-Length | 1234 | Required. This value should be set to the exact length of the message body you are sending. |
| Authorization | Bearer | Required. |
| x-nabwss-appsource | pa_isv_1234567890abc | Required. This value is specific to each individual API account. For example, ISVs selling an application to multiple companies would use a different value for each company. Similarly, if a user has multiple accounts (MIDs) with us, the value for the x-nabwss-appsource header would be different for each MID. |
Request body:
| Parameter | Description |
|---|---|
| latitude | Optional |
| longitude | Optional |
| customer | Optional |
| first_name | Optional |
| last_name | Optional |
| email_addresses | Optional |
| name | Product name |
| description | Product description |
| number | Invoice number |
| due_date | Use current date |
| send_date | Use current date |
| amount | Amount in dollars |
| tax_rate | Percent |
| service_fee_enabled | Optional boolean value that enables or disables the service fee (also referred to as Cash Discount) on a per transaction basis. The Cash Discount value is set at the account level at the time the merchant account is created, and is either a percentage or a fixed dollar amount. If Cash Discount is enabled at the account level, even if the service_fee_enabled parameter is not included in a request, Cash Discount will still be applied unless service_fee_enabled is passed with a value of false. This enables Cash Discount to be turned off on a per transaction basis. If Cash Discount is disabled at the account level, the service_fee_enabled flag will be ignored at all times. To view the Cash Discount setting associated with your account, log into the Payments Hub Merchant Portal and navigate to the Cash Discounting section. |
JSON response:
3. Present the URL received in the previous step to the user in an iFrame or separate browser window. From there, the user can enter their credit card information and click “Pay Now.”
Those using an iFrame will need to provide us with the following information:
- MID(s) that want to use an iFrame.
- Domain Names (DNS) for the merchant's website.
4. Let us know if you would like us to set up a webhook so your server can be notified when a payment is approved or declined. The following information will be required to set up the webhook:
- MID(s) to enable the webhook on.
- The full URL which North will post the payment result to. This must be on HTTPS and the site must use a certificate from a CA (not self-signed) in order to work.
Your endpoint should be configured to receive a payload that looks like the following:
| Parameter | Description |
|---|---|
| unique_id | Unique ID for this transaction, provided by Payanywhere. You can use this field in the Payanywhere system to track your transaction |
| auth_code | Auth code for this transaction |
| amount | Authorized charged amount that was applied on this transaction |
| status | Either “APPROVED” or “DECLINED” |
| is_partial_auth | A partial auth transaction occurs when you try to charge a card a certain amount, i.e. $20, but that card has only a portion of that amount available, i.e. $15, and your transaction is partially approved with $15. For example, this could occur with a gift card |
| requested_amount | Requested charge amount |
| receipt_id | Receipt ID |
| bric | This will be your token |
| invoice_number | An invoice id provided by you. You can use this id to match between a transaction request that was sent by your web app and a transaction response that will be sent to your external notification URL |
Bulk Invoice Import
You can create and send many invoices at once by uploading a CSV file. Use the same auth token and accountId from the Gateway Invoicing API Setup section above. The flow is: create an import, check status or fix errors, then send (or cancel/discard) the import.
Create a bulk import
1. Upload a CSV file by sending a POST request to the imports endpoint. Refer to the CSV specification for requirements regarding fields and formatting.
Method: POST
Request URL: https://proxy.payanywhere.com/accounts/<ACCOUNT_ID>/imports
Headers:
| Name | Value | Description |
|---|---|---|
| Content-Type | multipart/form-data | Required for file upload. |
| Authorization | Bearer JWT | Required. |
| x-nabwss-appsource | pa_isv_1234567890abc | Required. This value is specific to each individual API account. |
Request body (multipart/form-data):
| Field | Description |
|---|---|
| file | Required. The CSV file (e.g. use the default template or your own with mapping). Refer to the CSV specification for requirements regarding fields and formatting. |
| type | Required. Use invoices for bulk invoicing. |
| transaction_source | Optional. e.g. PH-Portal|6.9 |
| latitude | Optional. |
| longitude | Optional. |
| mapping | Optional. For custom CSV columns: {"fields": {"your_column": "Customer Email Address"}, "name": "My Mapping", "save": true}. Provide name when save is true. |
| mapping_id | Optional. Use a saved mapping ID when reusing a custom mapping. |
JSON response (HTTP 201):
If the CSV has validation errors, the response includes import_errors (headers, error_rows, errors_by_column) and error_file_url to download a file with the rows that failed. Fix those rows and re-upload, or use the fix-errors action in the next section.
| HTTP Status | Description |
|---|---|
| 400 | Account invalid, no file, missing headers/type, invalid mapping, or missing mapping name when save is true. Response: {"reason": "bad request"} |
| 403 | User or role not valid for invoices. Response: {"reason": "forbidden"} |
| 404 | Mapping id not found, inactive, or belongs to another merchant. Response: {"reason": "not found"} |
Get an import
2. Retrieve a single import by ID to check status, progress, or error details.
Method: GET
Request URL: https://proxy.payanywhere.com/accounts/<ACCOUNT_ID>/imports/<IMPORT_ID>
Optional query parameters: verbose (for full error details), type (e.g. report for invoice/series and totals), transaction_source (e.g. PH-Portal|6.9).
Headers: Include Authorization: Bearer JWT and x-nabwss-appsource.
JSON response (HTTP 200):
With verbose=true the response can include import_errors and error_file_url. With type=report it can include invoices, series, total_customers, and total_invoice_volume.
Send, cancel, discard, or fix errors
3. Update an import with a PUT request. Use action to send, cancel, discard, or fix specific error rows.
Method: PUT
Request URL: https://proxy.payanywhere.com/accounts/<ACCOUNT_ID>/imports/<IMPORT_ID>
Headers: Content-Type: application/json, Authorization: Bearer JWT, x-nabwss-appsource.
Request body examples:
Send invoices:
Cancel or discard:
or "action": "discard".
Fix a single error row (use the row index from import_errors):
When action is send, response (HTTP 201) may be:
When action is cancel, discard, or fix-errors, response includes the updated import object (e.g. status, invoices).
| HTTP Status | Description |
|---|---|
| 400 | Account or import invalid, or import already canceled/discarded. For fix-errors, rowIndex may be invalid: {"reason": "Bad Request: Unknown error row index has been provided"} |
| 403 | {"reason": "forbidden"} |
Get bulk import records
4. List imports for the account with optional pagination and filtering.
Method: GET
Request URL: https://proxy.payanywhere.com/accounts/<ACCOUNT_ID>/imports
Optional query parameters: cursor (page indicator), status (filter by status), transaction_source (e.g. PH-Portal|6.9).
Headers: Authorization: Bearer JWT, x-nabwss-appsource.
JSON response (HTTP 200):
| HTTP Status | Description |
|---|---|
| 400 | User or account id invalid. {"reason": "bad request"} |
| 404 | Account id does not exist. {"reason": "not found"} |
| 403 | {"reason": "forbidden"} |