Cards & Wallets · PaySuite payment page

Account Verification

Check a customer's card on our payment page without taking a payment: create a hosted account verification session, send your customer to it, then retrieve the session status to find out what happened.

Create a verification session

There is no amount on a verification, so money carries the currency only. This example checks the card and keeps nothing.

Create a verification session
EndpointDefinition
POST /hosted/rest/sessions/{instId}/verify
Request body
{
  "session": {
    "returnUrl": {
      "url": "https://www.example.com/return"
    }
  },
  "transaction": {
    "money": {
      "currency": "GBP"
    },
    "merchantReference": "aReference"
  },
  "verification": {
    "acquirerPaymentMethod": true
  }
}
cURL
curl -X POST "{targetEnvironmentPath}/hosted/rest/sessions/{instId}/verify" \
  -u "{apiUser}:{apiPassword}" \
  -H "Content-Type: application/json" \
  -d '{
  "session": {
    "returnUrl": {
      "url": "https://www.example.com/return"
    }
  },
  "transaction": {
    "money": {
      "currency": "GBP"
    },
    "merchantReference": "aReference"
  },
  "verification": {
    "acquirerPaymentMethod": true
  }
}'
Response
HTTP/1.1 201 Created

{
  "sessionId": "SMjpYJ1ccAApNjaXhjMH1RprT",
  "redirectUrl": "https://secure.mite.pay360.com/hosted/SMjpYJ1ccAApNjaXhjMH1RprT/begin/SMjpYJ1ccAApNjaXhjMH1RprT",
  "status": "SUCCESS"
}
Notes:
  • The currency reference uses the ISO 4217 alphabetic code.
  • The customer's browser will be redirected to the returnUrl once the verification has finished.
  • In the response the key field is status. SUCCESS means the hosted session is ready, anything else is a failure.
  • Only on success, redirect the user's browser to the returned url, or include it in your site within an iframe, and the customer will be presented with the card form.
  • The response field sessionId is our unique id for this hosted session. Keep this to retrieve the status of the session.
  • New fields may be added to the response at any time, so ensure your integration will not mind unexpected response elements. Existing response fields will not be removed without notice.
  • A hosted session binds to the first browser to visit the redirectUrl, any attempts to visit the hosted session from another browser will produce an error page.

Saving the card for future reuse

Add a customer to the session and we hold the verified card against them, ready to reuse for later payments. These are the minimal details needed.

Everything described in saving cards for reuse applies here — the cardholder agreement you must display, the stored credentials framework, and how a saved card can be re-used afterwards.

Create a verification session saving the card
EndpointDefinition
POST /hosted/rest/sessions/{instId}/verify
Request body
{
  "session": {
    "returnUrl": {
      "url": "https://www.example.com/return"
    }
  },
  "transaction": {
    "money": {
      "currency": "GBP"
    },
    "merchantReference": "aReference"
  },
  "verification": {
    "acquirerPaymentMethod": true
  },
  "customer": {
    "identity": {
      "merchantCustomerId": "aNewCustomerId"
    },
    "details": {
      "name": "Test Customer"
    }
  }
}
cURL
curl -X POST "{targetEnvironmentPath}/hosted/rest/sessions/{instId}/verify" \
  -u "{apiUser}:{apiPassword}" \
  -H "Content-Type: application/json" \
  -d '{
  "session": {
    "returnUrl": {
      "url": "https://www.example.com/return"
    }
  },
  "transaction": {
    "money": {
      "currency": "GBP"
    },
    "merchantReference": "aReference"
  },
  "verification": {
    "acquirerPaymentMethod": true
  },
  "customer": {
    "identity": {
      "merchantCustomerId": "aNewCustomerId"
    },
    "details": {
      "name": "Test Customer"
    }
  }
}'
Response
HTTP/1.1 201 Created

{
  "sessionId": "SMjpYJ1ccAApNjaXhjMH1RprT",
  "redirectUrl": "https://secure.mite.pay360.com/hosted/SMjpYJ1ccAApNjaXhjMH1RprT/begin/SMjpYJ1ccAApNjaXhjMH1RprT",
  "status": "SUCCESS"
}

Verifying a card we already hold

Once we know the customer, their reference on its own is enough — we take the card details we already hold, and the customer only types in their CV2.

Create a verification session for an existing customer
EndpointDefinition
POST /hosted/rest/sessions/{instId}/verify
Request body
{
  "session": {
    "returnUrl": {
      "url": "https://www.example.com/return"
    }
  },
  "transaction": {
    "money": {
      "currency": "GBP"
    },
    "merchantReference": "aReference"
  },
  "verification": {
    "acquirerPaymentMethod": true
  },
  "customer": {
    "identity": {
      "merchantCustomerId": "anExistingCustomer"
    }
  }
}
cURL
curl -X POST "{targetEnvironmentPath}/hosted/rest/sessions/{instId}/verify" \
  -u "{apiUser}:{apiPassword}" \
  -H "Content-Type: application/json" \
  -d '{
  "session": {
    "returnUrl": {
      "url": "https://www.example.com/return"
    }
  },
  "transaction": {
    "money": {
      "currency": "GBP"
    },
    "merchantReference": "aReference"
  },
  "verification": {
    "acquirerPaymentMethod": true
  },
  "customer": {
    "identity": {
      "merchantCustomerId": "anExistingCustomer"
    }
  }
}'
Response
HTTP/1.1 201 Created

{
  "sessionId": "SMjpYJ1ccAApNjaXhjMH1RprT",
  "redirectUrl": "https://secure.mite.pay360.com/hosted/SMjpYJ1ccAApNjaXhjMH1RprT/begin/SMjpYJ1ccAApNjaXhjMH1RprT",
  "status": "SUCCESS"
}

Retrieve the session status

Find out whether the card was verified by retrieving the session status, exactly as you would for a payment session.