Payments API

27/05/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

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.

Implementations

We have an open source web-to-print payments gateway implementation for PayPal Pro via a WordPress plugin.

See also: