Payments API

API & integration, credit cards, Payments

May 27th, 2009

Customer payments can be processed by PayPal directly or by any other custom gateway via API. You can accept payment for your web-to-print and dynamic imaging services via any payments provider as long as you implement a gateway.

Transaction initiation

Your web-to-print portal prepares a transaction the same way for PayPal and a custom gateway, except for the destination URL and notify_url field.

List of fields:

xclick = cmd
notify_url
amount
no_shipping
item_name
currency_code
business
cancel_return
return
address1
address2
city
country
state
zip

Address, city, country, state and zip fields are included if your web-to-print catalog is configured to use structured address.

These fields are posted to the address specified in Accept Payments Online section of account details.

web-to-print gateway

Gateway response

The gateway has to accept the HTTP POST data from your web-to-print portal, package it into some other required format and process the payment. Once the payment is processed, the gateway should send an independent confirmation back to your web-to-print portal.

Field notify_url contains the address of the response. The gateway must also provide the following data:

ApiKey – the API key to access your web-to-print portal, e.g. [notify_url string];ApiKey=6D483859-BBEC-4DA4-B6BB-63BCBEB69A6E, or it can be a POST field. Requests with invalid or with no ApiKey are rejected.
payment_status – values “completed” or “processed” for successfully completed transactions or any other value for pending or rejected transactions.
payment_gross – numeric value of the total amount paid to compare against the amount billed

Other fields can also be included in the response. The will be stored in the DB and can be retrieved via an API call. The following fields are recognised and showing as part of order details:

mc_gross
protection_eligibility
address_status
payer_id
tax
address_street
payment_date
charset
address_zip
first_name
mc_fee
address_country_code
address_name
notify_version
custom
payer_status
business
address_country
address_city
quantity
verify_sign
payer_email
txn_id
payment_type
last_name
address_state
receiver_email
payment_fee
receiver_id
txn_type
item_name
mc_currency
item_number
residence_country
receipt_id
handling_amount
transaction_subject
payment_gross
shipping
payment_status

Confirmation response

Possible responses from ZetaPrints web-to-print portal to a payments notification:

<ok /> – the request was processed
<error /> – there were problems with processing, do not try again
some other error (500, communication, etc. ) – try again after some time
404 or 410 response - invalid ids, wrong API key or some other access error, do not try again

It is up to the gateway to repeat the confirmation request on error or not.