Processing a Payment

Processing a payments (in its simple flow) is an operation made in two steps:

  1. Create a payment on Flyt: This step does not depend by the payment flow and it is used to validate that the payment is actually ready to be sent to the payment service.
  2. Send the payment to the payment service: This step could vary accordingly to the requested flow and could consist of one or more API calls.

Please note that:

  • From now on is not important which payment service is configured at the location (Adyen or Cybersource). The API calls to make are the same regardless the location setup.

Initialization and capture of a payment

Initialization, auth, cancelling an auth and capture of a payment.

Creating a payment

In order to validate a payment and make sure we’re ready for a money transfer, the first step required is initialise the payment on Flyt

curl -X "POST" "http://api.flypaythis.com/payments/v1/payment?accessToken={accessToken}" \
     -H 'Content-Type: application/json' \
     -d $'{
            "amount": 124,
            "cardId": 2,
            "locationId": 3778
          }'
Field Description
amount Amount in decimals to pay.
cardId The card id correctly tokenized for the payment service set up on the location. The card Id could be retrieved in the wallet .
locationId The Flyt location id to send the money to

Under the hood, we validate the payment and location information.

Response

A successful response returns the HTTP code 201 and paymentHash:

{
  "hash": "c30fae0aa048d2c08cb69d1dc71f186d"
}

You can proceed to call Auth and Charge in one endpoint or if you need more control, calling the endpoints: Auth a payment and Charging the auth separately.

Possible error at this stage:

Invalid payload

Something is missing or appear to be invalid in the payload passed. In this case the error returned is a 400 - Bad Request.

To fix this, check the request payload and send it again.

Authorization Error

The user is not logged in or is not able to perform this operation. In this case the http code returned is a 401 - Unauthorized.

To fix this check you’re passing a correctly logged in access token. To obtain one, make a bootstrap and then login

Resource Forbidden

The user has been blocked because of a high fraud score and therefore is not able to proceed with the request. The error code returned is a 403 - Forbidden.

Payment already processed

The payment result already processed. The error code returned is a 409 - Conflict.

To fix this, if you really want to go through this validation, send the flag confirmDuplicate as true in the request. Be careful that payment could be duplicated for the final user.

Card not tokenized

In this case the card doesn’t result tokenized for the payment service setup at the location. Even in this case the http status code returned will be a 409 - Conflict.

To fix this, follow the guide on how adding a card to a wallet

Auth and Charge

If the call to Creating a payment succeeded and returned a payment hash, we can proceed to authorise and capture the payment. This endpoint allows you to do both operations at the same time for convenience.

What happen at this stage is the second step of the diagram at the top of the page. A call to the endpoint is what you need to do to send the payment to the configured payment service at the location and make an actual money transfer. In this case the only parameter required is the card cvc.

curl -X "POST" "http://api.flypaythis.com/payments/v1/payment/{paymentHash}/auth-and-charge?accessToken={accessToken}" \
     -H 'Content-Type: application/json' \
     -d $'{
            "cvc": "131"
          }'
Field Description
cvc The payment card CVC

Response

If the card is not enrolled for a 3DSecure payment, the API returns a HTTP 204 code and the money is transferred from the customer card to the location bank account.

3DSecure payment

3DSecure is an XML-based protocol designed to be an additional security layer for online credit and debit card transactions. What is required by the customer in this case is having a validation step (with no user interaction for many banks) in order to confirm the card is safe and proceed to the capture of the payment.

Completing a payment through the 3DS flow

If the card is enrolled for 3DSecure, the call on the /auth-and-charge or (/auth) endpoint returns a 402 - Payment required error (with error code 402002) that looks like this:

{
  "error": true,
  "code": 402002,
  "message": "Secure Payment (3DS pending)",
  "contextData": {
    "hash": "c469f48c51374c3d63f95c25e2bef79f",
    "3ds": {
      "enrolled": true,
      "ascUrl": "https://test.adyen.com/hpp/3d/validate.shtml",
      "paReq": "eNpVUdtOg0AQ/ZXqB7CXukDJdBNaovJARcUHnwzZji1JoXRZTOvXu0uL1Xmac+Z+BoqtRkxeUfUaJWTYdeUGJ9V6fhuFIRPcp3zGAhH4AbuVkMcveJDwhbqr9o1kHvU4kBHacq22ZWMklOqwSFdSMD69A3JBUKNOE1lgZ/K6jtWhrzRqIGcamrJG+RZ/xMub6H53astTWgAZWFD7vjH6JEPuAxkB9Hont8a0ESGfQ4FXGSCOBXLdJe+d19kux2otn5LNcVWkPEtSkRWKrb7fp9lz7GwOxGXAujQoOWUhFYxNaBiJWTQVQAYeytqNlw+LfCKEF1B73pmB1g2Kz0AIF/nLgJVYY6PGI0YEeGz3DdoMK+WvD+S69vLRCaqMFUlwp6jwg3BGR22HgOtSWU3s0uHQxgEgrpRcvkYu37Xev6//AGQap+c=",
      "md": "djIhdjY2eTJjREtlaVY1UFZkSjlQanZsQT09IVml+HF9ERvnyramPcfO9P2VDIsmMeDETTFwo/Tmhy1EHHItObQlbl20j7ebXyzB9aVe8XhBGEWYDrE8bsEBliagBIZnUU/f3HaEBSiWCA6REwdTyvTm6Q6CutRnPvcMwPAkXpb4AbNkzYbWLIN0j9q8e9jyrcNcqSsCj1qfE8DATkThCyo2qWC0EPJFp63s4sywgXsBhXuSgTkpOCrZW8H2ktFrm6I5VzU7WXjgudjk2hCWQEO3gmSYvQcSHxgSJujX9E4pYVu2cieRZiqKT6Hi3F1xP5qj+HRNmXh6PqnmqEwnoonAiCRNP2E9",
      "termUrl": "https://api.flypaythis.com/v2/payment/3ds/callback"
    }
  },
  "displayString": null,
  "requestInfo": {
    "accessTokenStatus": "authenticated",
    "serverTime": 1526029175,
    "requestId": null,
    "apiVersion": 0
  }
}

What is required at this stage is to implement a simple web application to complete the validation step. What is required to send through are:

  • ascUrl is the action of the form, the address where to send the parameters
  • paReq
  • MD
  • termUrl a flyt API endpoint used to complete the validation step.

The following html page could help you to test your application: 3DS validation page

What you need to change is the action of the form by using the ascUrl returned in the 402 error (that depends by the card issuer, so it always change).

The user could be asked to insert a password at this stage, but more likely what happens is just a silent check, with no user interaction. At the end of this step, the page will show a string success or failure. If the operation succeeded, we’re able to call the auth-and-charge or auth endpoint again and complete the payment. If the result of the validation step is a failure, the 3DSecure didn’t passed the validation and to try again to make the payment you should repeat the whole flow.

Possible error at this stage:

Invalid payload

Something is missing or appear to be invalid in the payload passed. In this case the error returned is a 400 - Bad Request.

To fix this, check the request payload and send it again.

Authorization Error

The user is not logged in or is not able to perform this operation. In this case the http code returned is a 401 - Unauthorized.

To fix this check you’re passing a correctly logged in access token. To obtain one, make a bootstrap and then login

Resource Forbidden

The user has been blocked because of a high fraud score and therefore is not able to proceed with the request. The error code returned is a 403 - Forbidden.

Resource Not Found

The payment hash passed in the request has not been found in the database. The error returned is a 404 - Not found.

To fix this check the payment hash and make the request again.

Payment already processed

The payment result already processed. The error code returned is a 409 - Conflict.

To make the payment again, restart the process from step 1.

Payment Failed

The payment service does not appear online and then the payment can’t be completed. In this case the error returned is a 503 - Service Unavailable.

Try again later to complete the payment.

Auth a payment

You’ll require the paymentHash you get from the Creating a payment response along with the card CVC.

curl -X "POST" "https://api.flypaythis.com/payments/v1/payment/{paymentHash}/auth?accessToken={accessToken}" \
     -H 'Content-Type: application/json' \
     -d $'{
            "cvc": "123"
          }'
Field Description
cvc The payment card CVC

You can proceed to Charging the auth or Cancelling the auth.

Charging the auth

You’ll first have to Auth a payment to be able to charge it.

curl -X "POST" "https://api.flypaythis.com/payments/v1/payment/{paymentHash}/charge?accessToken={accessToken}"

If everything goes to plan you’ll get a HTTP 204. See the API documentation for other response types.

Cancelling the auth

You’ll first have to Auth a payment to be able to cancel it

curl -X "DELETE" "https://api.flypaythis.com/payments/v1/payment/{paymentHash}/auth?accessToken={accessToken}"

If everything goes to plan you’ll get a HTTP 204 and the auth will be cancelled. See the API documentation for other response types.