This page is a ZenPay-styled copy of the Zenith Payments developer documentation. View the original docs

Card Proxies API

A card proxy is a secure tokenized reference to a credit or debit card. Card proxies allow PCI-compliant payment processing without handling raw card numbers.

Create a card proxy#

POST/v2/cardproxies

View this endpoint in the original docs

Creates a card proxy from the supplied card details. Not recommended for software or sites that are not PCI DSS compliant. For an easy and secure card tokenisation and payment option, see the Payment Plugin.

Authentication: Api-Key + BasicAuth

Request body

Card details required to create a card proxy.

Content types: application/json, application/x-www-form-urlencoded · required

Schema: CardProxyRequest

Field	Type	Description
`cardHolderName`	string	Card holder name.
`cardNumber` required	string	Credit/Debit Card number.
`customerUniqueId`	string	Customer unique identifier.
`expiry` required	string	Card expiry in MM/yy format.
`paymentAmount`	number <double>	Amount is optional. If provided, the applicable pricing will be returned in the result.
`threeDSecureData`	object (ThreeDSecureData)	Conditional. Pass the values if 3DSecure is required.

Example: Card tokenised with pricing

Same basic request as above, plus a payment amount over 1, so the response comes back with the applicable fee — no 3-D Secure data needed to see pricing.

JSON

{
  "cardHolderName": "Test Cardholder",
  "cardNumber": "5555555555554444",
  "customerUniqueId": "recap-1297842247644",
  "expiry": "12/29",
  "paymentAmount": 100
}

Example: Card tokenised, 3-D Secure pending

Shows the authentication handoff; token creation alone does not prove challenge completion.

JSON

{
  "cardHolderName": "Test Cardholder",
  "cardNumber": "5555555555554444",
  "customerUniqueId": "recap-3ds-1824624376604",
  "expiry": "12/29",
  "paymentAmount": 1,
  "threeDSecureData": {
    "browserData": {
      "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
      "colorDepth": 24,
      "ipAddress": "203.0.113.10",
      "language": "en-AU",
      "screenHeight": 1080,
      "screenWidth": 1920,
      "timezone": "-600",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36"
    },
    "callbackUrl": "https://httpbin.org/post?uniqueId=[uniqueId]&status=[status]",
    "redirectUrl": "https://httpbin.org/get",
    "useThreeDSecure": true
  }
}

Example: Card tokenised, basic request

Smallest captured successful tokenisation request; the same customerUniqueId sent again is the paired 409 below.

JSON

{
  "cardHolderName": "Test Cardholder",
  "cardNumber": "5555555555554444",
  "customerUniqueId": "dup-6052133113378",
  "expiry": "12/29"
}

Responses

201 Card authorisation is successful.

application/json · object (CardProxyResponse)

Example: Card tokenised with pricing

Same basic request as above, plus a payment amount over 1, so the response comes back with the applicable fee — no 3-D Secure data needed to see pricing.

JSON

{
  "cardNumber": "555555XXXXXX4444",
  "cardProxy": "92879c54c08a45f9a0b92ffb6f1966c7",
  "cardType": "MasterCard",
  "expiry": "1229",
  "pricing": {
    "customerFee": 0,
    "merchantFee": 0,
    "paymentAmount": 100,
    "processingAmount": 100
  },
  "status": "Successful"
}

Example: Card tokenised, 3-D Secure pending

Shows the authentication handoff; token creation alone does not prove challenge completion.

JSON

{
  "cardNumber": "555555XXXXXX4444",
  "cardProxy": "e1f1ef1e7e22468eaeaa42d9b5ed1d36",
  "cardType": "MasterCard",
  "expiry": "1229",
  "pricing": {
    "customerFee": 0,
    "merchantFee": 0,
    "paymentAmount": 1,
    "processingAmount": 1
  },
  "redirectUrl": "https://pay.sandbox.b2bpay.com.au/3dsecure/e1f1ef1e-7e22-468e-aeaa-42d9b5ed1d36/CardProxiesApi",
  "status": "PendingThreeDS"
}

Example: Card tokenised, basic request

Smallest captured successful tokenisation request; the same customerUniqueId sent again is the paired 409 below.

JSON

{
  "cardNumber": "555555XXXXXX4444",
  "cardProxy": "93283bd2477b47dd856986300e3803f0",
  "cardType": "MasterCard",
  "expiry": "1229",
  "status": "Successful"
}

400 Invalid input detail.

application/json · object

403 The credential provided doesn't support this endpoint.

Example: Tokenising not allowed

A business rule specific to this operation (tokenisation switched off for the account), the same class as a declined-credit 412; document the permission status.

JSON

""

409 Customer unique id is already used.

412 Tokenisation failed.

application/json · object (PreconditionFailedResponse)

Example request (cURL, sandbox host)

cURL

curl -X POST 'https://api.sandbox.zenpay.com.au/v2/cardproxies' \
  -H 'Api-Key: <your API key>' \
  -u '<username>:<password>' \
  -H 'Content-Type: application/json' \
  -d '{
  "cardHolderName": "Test Cardholder",
  "cardNumber": "5555555555554444",
  "customerUniqueId": "recap-1297842247644",
  "expiry": "12/29",
  "paymentAmount": 100
}'

Delete a card proxy#

DELETE/v2/cardproxies/{cardProxy}

View this endpoint in the original docs

Deletes the specified card proxy without affecting customers already registered with it.

Authentication: Api-Key + BasicAuth

Parameters

Name	In	Type	Description
`cardProxy` required	path	string	The card proxy identifier.

Responses

204 Card proxy deleted successfully.

Example: Card proxy deleted

Deleting a token answers 204 with an empty body.

JSON

""

400 Invalid input detail.

application/json · object

404 Unable to find the Card proxy provided.

Example request (cURL, sandbox host)

cURL

curl -X DELETE 'https://api.sandbox.zenpay.com.au/v2/cardproxies/{cardProxy}' \
  -H 'Api-Key: <your API key>' \
  -u '<username>:<password>' \
  -H 'Accept: application/json'

Get a card proxy#

GET/v2/cardproxies/{cardProxy}

View this endpoint in the original docs

Returns the card proxy for the specified card proxy value.

Authentication: Api-Key + BasicAuth

Parameters

Name	In	Type	Description
`cardProxy` required	path	string	The card proxy identifier.

Responses

200 Token response of the card proxy provided.

application/json · object (TokenResponse)

Example: Card proxy details

Baseline lookup for this operation.

JSON

{
  "cardNumber": "555555XXXXXX4444",
  "cardProxy": "92879c54c08a45f9a0b92ffb6f1966c7",
  "cardType": "MasterCard",
  "expiry": "1229"
}

400 Invalid input detail.

application/json · object

404 Unable to find the token response for the card proxy provided.

Example request (cURL, sandbox host)

cURL

curl -X GET 'https://api.sandbox.zenpay.com.au/v2/cardproxies/{cardProxy}' \
  -H 'Api-Key: <your API key>' \
  -u '<username>:<password>' \
  -H 'Accept: application/json'

Get card proxy pricing#

GET/v2/cardproxies/{cardProxy}/pricing

View this endpoint in the original docs

Returns pricing for the specified card proxy and payment amount.

Authentication: Api-Key + BasicAuth

Parameters

Name	In	Type	Description
`cardProxy` required	path	string	The card proxy identifier.
`paymentAmount` required	query	number <double>	The payment amount used to calculate pricing.

Responses

200 Pricing response for card proxy and payment amount provided.

application/json · object (PricingResponse)

Example: Card proxy pricing

Baseline pricing lookup; keep paymentAmount in the query-parameter documentation.

JSON

{
  "pricing": {
    "customerFee": 0,
    "merchantFee": 0,
    "paymentAmount": 1,
    "processingAmount": 1
  }
}

400 Invalid input detail.

application/json · object

404 Unable to find the pricing response for the card proxy provided.

Example request (cURL, sandbox host)

cURL

curl -X GET 'https://api.sandbox.zenpay.com.au/v2/cardproxies/{cardProxy}/pricing' \
  -H 'Api-Key: <your API key>' \
  -u '<username>:<password>' \
  -H 'Accept: application/json'

Need help with your integration?Talk to the Zenith Integrations Team.

Email integrations Talk to us