Upload Payment Instruction File

Syntax
Request Headers and Body
Request Parameters
Success Codes
Sample Response
Error Codes
Calling the API
- Postman
- cURL
- Python

Syntax

POST /api/payment-instructions/load/

… with the payment instruction file for upload passed in. the request body.

The user performing this request must be authorized to upload Payment Instruction Files.

Example:

POST /api/payment-instructions/load/ HTTP/1.1
Host: sandbox.paymentworks.com
Authorization: Token 5e4eXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX1ba
Content-Length: 221
Content-Type: multipart/form-data;
boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data;
name="payment-instructions";
filename="test-payment-instruction-file.txt"
Content-Type: text/plain

(data)
------WebKitFormBoundary7MA4YWxkTrZu0gW--

See sections below for examples of how to make PIF upload API requests via Postman or cURL.

Request Headers and Body

The payment instruction file for upload must be provided in the request body under the key name payment-instructions.

To be able to provide a file here, the Content-Type must be set to multipart/form-data

This authorized user’s API token must also be included in the request header.

Request Parameters

This API does not take any parameters.

Success Codes

HTTP Status Code	Exception	Description
200	Success	A successful PIF upload will return a 200 Status Code and JSON response body that indicates a success status and the name of the uploaded file.

Response

Returns a JSON object with information pertaining to the upload attempt.

Examples:

Successful Response

{
"status":"ok",
"file_name":"test_payment_instruction_file.txt",
"job_id":"2-2b9e41f0003d47d9aa1831a821e95274"
}

Errored Response

{
"status": "error",
"error": "User does not have permission to upload payment instruction files"
}

The important response fields include:

Key	Type	Sample Value	Description
status	String	ok error	Single word indication of PIF upload success/failure.
file_name	String	test_payment_instruction_file.txt test_encrypted_pif.pgp.decrypted	The name of the successfully uploaded file. Encrypted PIFs will be decrypted on upload, so the returned filename will have the .decrypted suffix.
error	String	User does not have permission to upload payment instruction files.	A more specific error message indicating what went wrong, included in the response if the request did not succeed.

Error Codes

HTTP Status Code	Exception	Description
400	Bad Request	The request could not be understood by the server due to incorrect syntax.
401	Unauthenticated	The request requires user authentication information. Your API token is missing or invalid.
403	Forbidden	Unauthorized request. The client does not have access rights to the content. Unlike 401, the client’s identity is known to the server.
404	Not Found	The API that you requested does not exist on this server.
500	Service Unavailable	The server encountered an unexpected condition that prevented it from fulfilling the request.
503	Service Unavailable	The request has failed due to a temporary failure of the server. You can try this request at a later time.

Calling the API

Postman

Call Syntax:

{
	"name": "upload_payment_instruction_file",
	"request": {
		"auth": {
			"type": "oauth2",
			"oauth2": [
				{
					"key": "headerPrefix",
					"value": "Token",
					"type": "string"
				},
				{
					"key": "addTokenTo",
					"value": "header",
					"type": "string"
				}
			]
		},
		"method": "POST",
		"header": [],
		"body": {
			"mode": "formdata",
			"formdata": [
				{
					"key": "payment-instructions",
					"type": "file",
					"src": "/path/to/file/test-payment-instruction-file.txt"
				}
			]
		},
		"url": {
			"raw": "https://sandbox.paymentworks.com/api/payment-instructions/load/",
			"protocol": "https",
			"host": [
				"sandbox",
				"paymentworks",
				"com"
			],			
			"path": [
				"api",
				"payment-instructions",
				"load",
				""
			]
		}
	},
	"response": []
}

Passing files in the request body with Postman

Hovering over the right side of the Key column reveals a dropdown that allows the user to input a File for the Value instead of Text. Clicking the Select Files button that appears in the Value column brings up a file explorer that allows the user to select the file to include in the request body.

Sample call in Postman

cURL

Python

import requests
import json
import os

# These variables should be set as OS environment variables
API_TOKEN = os.environ.get('API_TOKEN')
# The value should be the API url, for example: https://sandbox.paymentworks.com/api/
API_URL = os.environ.get('API_URL')

request_headers = {
  'Authorization': 'Token ' + API_TOKEN
}

# Attempts payment instruction file API upload and returns response
def upload_pif_via_api(file_name, full_file_path):
    resp = None
    request_path = API_URL + 'payment-instructions/load/'
    payload = {}
    files = [
      ('payment-instructions',(file_name, open(full_file_path,'rb'),'text/plain'))
    ]
    try:
       resp = requests.post(url=request_path, 
                            headers=request_headers,
                            data=payload,
                            files=files,
                            timeout=10)    
    except Exception as exception:
        print(f'Unexpected {exception=}, {type(exception)=}') 
    return resp

# Main function
response = upload_pif_via_api('test_pif.txt', '/path/to/test_pif.txt')
if response is not None:
    if response.status_code == 200:
        print(json.loads(response.text))
    else:
        print('Return Status Code: ' + str(response.status_code))