Payment API

Overview ¶

With the Payment API you can integrate payment functionality into your website/shop. This is easily done by sending HTTP requests to each other.

This documentation gives an overview of the Payment API and its current functionalities.

Supported payment methods:

PayPal

For using this Payment API you need a merchant account provided by us. Need a merchant account? send a email to info@alphacommsolutions.com.

Endpoint usage ¶

We have two types of flows based on your contract. use the section of the documentation that matches your contract.

Flows
- DIRECT
- CHECKOUT

We have two endpoints ACCEPTANCE endpoint for merchant test purposes and a LIVE endpoint when a merchant is done testing and ready for receiving payments.

Endpoints
- LIVE https://riskfreecheckout.com
- ACCEPTANCE https://acceptance-payment.acpsit.nl

Acquire access token ¶

Request access token ¶

Create new Access token
GET`/oauth/v2/token?client_id={clientId}&client_secret={clientSecret}&grant_type=client_credentials`

Example URI

GET https://riskfreecheckout.com/oauth/v2/token?client_id=clientId&client_secret=clientSecret&grant_type=client_credentials

URI Parameters

HideShow

clientId: string (required)
clientSecret: string (required)

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "access_token": "NDAzM2MzNjRlMjY2ZmY0ZWM4MjdjOWYxZWMyOGQxZjYyNmVlNTFjYjEzMjQ3MTdhOWFhYjNkOTQ2N2Q0NmRjNw"
}

Create Checkout payment ¶

Forex checkout payment ¶

Your contract connectiontype is forex implement the request below.

issuerId is a valid iDeal issuer id returned in the call to payment-methods

Forex checkout payment
POST`/api/checkout`

Example URI

POST https://riskfreecheckout.com/api/checkout

Request

HideShow

Headers

Content-Type: application/json

Body

{
    "id": "31e5fa51-2475-455d-b0ad-5febd25434c5",
    "paymentMethod": "ideal",
    "issuerId": "RABONL2U"
    "returnUrl": "http://www.example.com/order/return",
    "companyName": "Alphacomm",
    "logo": "http://www.alphacomm.nl/logo.png",
    "payer": {
        "id": "1337",
        "firstName": "John",
        "lastName": "Doe",
        "street": "Scheepmakerspassage 183",
        "city": "Rotterdam",
        "zipcode": "3011VH",
        "phone": "+31612345678",
        "email": "john@alphacomm.nl",
        "country": "NL",
        "ipAddress": "127.0.0.1",
        "language": "nl",
        "status": "registered",
        "verificationStatus": "phone",
        "accountType": "Platinum",
        "dateRegistration": "2016-01-01 13:56:48",
        "dateLastUpdated": "2016-01-01 13:56:48",
        "dateFirstPurchase": "2016-01-01 13:56:48",
        "withdrawalHistory": [
            {
                "datetime": "2016-01-01",
                "id": "1",
                "description": "transaction description",
                "amount": 10000
            }
        ],
        "cashBalance": 10000,
        "bonusBalance": 10000,
        "openPositionCost": 10000,
        "binaryHistory": [
            {
                "datetime": "2016-01-01",
                "id": "1",
                "description": "transaction description",
                "amount": 10000
            }
        ],
        "forexHistory": [
            {
                "datetime": "2016-01-01",
                "id": "1",
                "description": "transaction description",
                "amount": 10000
            }
        ]
    },
    "transaction": {
        "reference": "12345",
        "currency": "EUR",
        "amount": 2000,
        "description": "Financial transaction",
        "lines": [
            {
                "name": "Product 1",
                "description": "euros",
                "quantity": 2,
                "amount": 1000
            }
        ]
    }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Require a self generated UUID v4"
    },
    "paymentMethod": {
      "type": "string",
      "description": "Optional payment method: `paypal`, this will skip the select-payment page"
    },
    "bankId": {
      "type": "enum",
      "description": "Optional bank only used for payment method `ideal`. possible values use label from request GET /ideal/banks"
    },
    "returnUrl": {
      "type": "string",
      "description": "Absolute url where the payer will be redirected to after `complete`/`failure`/`cancel` of the payment"
    },
    "companyName": {
      "type": "string",
      "description": "The companyName will be used as label for payer of the payment in the checkout"
    },
    "logo": {
      "type": "string",
      "description": "Absolute url to a png file, size 190x100px, which will be used as images for the payer of the payment checkout"
    },
    "payer": {
      "type": "object",
      "description": "Payer info provided by your system",
      "properties": {
        "id": {
          "type": "string",
          "description": "Payer ID"
        },
        "firstName": {
          "type": "string",
          "description": "Payer firstname"
        },
        "lastName": {
          "type": "string",
          "description": "Payer lastname"
        },
        "street": {
          "type": "string",
          "description": "Payer street"
        },
        "city": {
          "type": "string",
          "description": "Payer city"
        },
        "zipcode": {
          "type": "string",
          "description": "Payer zipcode"
        },
        "phone": {
          "type": "string",
          "description": "Payer full phone number, starting with country code (+31) (E.164 format)"
        },
        "email": {
          "type": "string",
          "description": "Payer email address"
        },
        "country": {
          "type": "string",
          "description": "Country code 2 characters uppercase (ISO 3166-1 alpha2)"
        },
        "ipAddress": {
          "type": "string",
          "description": "Payer IP address of it's current session"
        },
        "language": {
          "type": "string",
          "description": "Payer Language code 2 characters lowercase (ISO 639-1)"
        },
        "status": {
          "type": "enum",
          "description": "Enum options: `guest`, `registered`, `registered-unconfirmed`"
        },
        "verificationStatus": {
          "type": "string",
          "description": "`identification`: Identification card/passport present, `phone`: verified by phone, `trusted`: trusted with other proof of identification, `otherwise`: otherwise"
        },
        "accountType": {
          "type": "string",
          "description": "Payer account type, Example: `silver`, `gold`, `platinum`"
        },
        "dateRegistration": {
          "type": "datetime",
          "description": "Datetime of payer account registration. Format (ISO 8601) 2016-11-22T11:39:21+0100"
        },
        "dateLastUpdated": {
          "type": "datetime",
          "description": "Datetime of payers last account update. Format (ISO 8601) 2016-11-22T11:39:21+0100"
        },
        "dateFirstPurchase": {
          "type": "datetime",
          "description": "Datetime of payers first purchase. Format (ISO 8601) 2016-11-22T11:39:21+0100"
        },
        "withdrawalHistory": {
          "type": "array",
          "description": "Array of withdrawal transaction history objects",
          "items": {
            "type": "object",
            "description": "Object of the withdrawal transaction history",
            "properties": {
              "datetime": {
                "type": "string",
                "description": "Transaction datetime, Format (ISO 8601) 2016-11-22T11:39:21+0100"
              },
              "id": {
                "type": "string",
                "description": "Transaction ID"
              },
              "description": {
                "type": "string",
                "description": "Transaction description"
              },
              "amount": {
                "type": "integer",
                "description": "Transaction amount in cents"
              }
            },
            "required": [
              "datetime",
              "id",
              "description",
              "amount"
            ]
          }
        },
        "cashBalance": {
          "type": "integer",
          "description": "Current amount of cash balance of the payer in cents"
        },
        "bonusBalance": {
          "type": "integer",
          "description": "Current amount of bonus balance of the payer in cents"
        },
        "openPositionCost": {
          "type": "integer",
          "description": "Current amount of open position cost of the payer in cents"
        },
        "binaryHistory": {
          "type": "array",
          "description": "Array of binary transaction history objects",
          "items": {
            "type": "object",
            "description": "Object of binary transaction history",
            "properties": {
              "datetime": {
                "type": "string",
                "description": "Transaction datetime. Format (ISO 8601) 2016-11-22T11:39:21+0100"
              },
              "id": {
                "type": "string",
                "description": "Transaction ID"
              },
              "description": {
                "type": "string",
                "description": "Transaction description"
              },
              "amount": {
                "type": "string",
                "description": "Transaction amount in cents"
              }
            },
            "required": [
              "datetime",
              "id",
              "description",
              "amount"
            ]
          }
        },
        "forexHistory": {
          "type": "array",
          "description": "Array of forex transaction history objects",
          "items": {
            "type": "object",
            "description": "Object of forex transaction history",
            "properties": {
              "datetime": {
                "type": "string",
                "description": "Transaction datetime. Format (ISO 8601) 2016-11-22T11:39:21+0100"
              },
              "id": {
                "type": "string",
                "description": "Transaction ID"
              },
              "description": {
                "type": "string",
                "description": "Transaction description"
              },
              "amount": {
                "type": "string",
                "description": "Transaction amount in cents"
              }
            },
            "required": [
              "datetime",
              "id",
              "description",
              "amount"
            ]
          }
        }
      },
      "required": [
        "id",
        "firstName",
        "lastName",
        "street",
        "city",
        "zipcode",
        "phone",
        "email",
        "country",
        "ipAddress",
        "language",
        "status",
        "verificationStatus",
        "accountType",
        "dateRegistration",
        "dateLastUpdated",
        "dateFirstPurchase",
        "withdrawalHistory",
        "cashBalance",
        "bonusBalance",
        "openPositionCost",
        "binaryHistory",
        "forexHistory"
      ]
    },
    "transaction": {
      "type": "object",
      "description": "Transaction data",
      "properties": {
        "reference": {
          "type": "string",
          "description": "Your transaction reference shown to the payer. This has to be alphanumeric, with a max of 32 characters."
        },
        "currency": {
          "type": "string",
          "description": "Currency code 3 characters format (ISO 4217)"
        },
        "amount": {
          "type": "integer",
          "description": "Amount in cents. Minimum value of 100 cents. Total amount of the transaction lines must be equal to this value"
        },
        "description": {
          "type": "string",
          "description": "Description of the transaction"
        },
        "lines": {
          "type": "array",
          "description": "Array of lines objects",
          "items": {
            "type": "object",
            "description": "Object of transaction line",
            "properties": {
              "name": {
                "type": "string",
                "description": "Item name"
              },
              "description": {
                "type": "string",
                "description": "Item description"
              },
              "quantity": {
                "type": "integer",
                "description": "Quantity of transaction item"
              },
              "amount": {
                "type": "integer",
                "description": "Amount in cents for a one quantity. Minimum value of 100 cents per quantity. Amount of all transaction lines must be equal to the transaction amount"
              }
            },
            "required": [
              "name",
              "description",
              "quantity",
              "amount"
            ]
          }
        }
      },
      "required": [
        "reference",
        "currency",
        "amount",
        "description",
        "lines"
      ]
    }
  },
  "required": [
    "id",
    "returnUrl",
    "companyName",
    "logo",
    "autoCapture",
    "payer",
    "transaction"
  ]
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": "7c8cca84-5745-4f2c-9701-8a685e544986",
  "amount": 2000,
  "currency": "EUR",
  "timestamp": "2017-02-06T15:24:39+0000",
  "status": "accepted",
  "paymentMethod": "paypal",
  "payerUrl": "Absolute checkoutUrl to redirect the payer to"
}

Create Direct payment ¶

Forex checkout payment ¶

Your contract connectiontype is forex implement the request below.

Forex direct payment
POST`/api/authorize`

Example URI

POST https://riskfreecheckout.com/api/authorize

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "id": "31e5fa51-2475-455d-b0ad-5febd25434c5",
  "paymentMethod": "paypal",
  "sessionId": "5d91b044-78b0-4f8e-abcd-b6ced4f9e81c",
  "returnUrl": "http://www.example.com/order/return",
  "companyName": "Alphacomm",
  "logo": "http://www.alphacomm.nl/logo.png",
  "autoCapture": true,
  "payer": {
    "id": "1337",
    "firstName": "John",
    "lastName": "Doe",
    "street": "Scheepmakerspassage 183",
    "city": "Rotterdam",
    "zipcode": "3011VH",
    "phone": "+31612345678",
    "email": "john@alphacomm.nl",
    "country": "NL",
    "ipAddress": "127.0.0.1",
    "language": "nl",
    "status": "registered",
    "verificationStatus": "phone",
    "accountType": "Platinum",
    "dateRegistration": "2016-01-01 13:56:48",
    "dateLastUpdated": "2016-01-01 13:56:48",
    "dateFirstPurchase": "2016-01-01 13:56:48",
    "withdrawalHistory": [
      {
        "datetime": "2016-01-01",
        "id": "1",
        "description": "transaction description",
        "amount": 10000
      }
    ],
    "cashBalance": 10000,
    "bonusBalance": 10000,
    "openPositionCost": 10000,
    "binaryHistory": [
      {
        "datetime": "2016-01-01",
        "id": "1",
        "description": "transaction description",
        "amount": 10000
      }
    ],
    "forexHistory": [
      {
        "datetime": "2016-01-01",
        "id": "1",
        "description": "transaction description",
        "amount": 10000
      }
    ]
  },
  "transaction": {
    "reference": "12345",
    "currency": "EUR",
    "amount": 2000,
    "description": "Financial transaction",
    "lines": [
      {
        "name": "Product 1",
        "description": "euros",
        "quantity": 2,
        "amount": 1000
      }
    ]
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Require a self generated UUID v4"
    },
    "paymentMethod": {
      "type": "string",
      "description": "Optional payment method: `paypal`, this will skip the select-payment page"
    },
    "sessionId": {
      "type": "string",
      "description": "Required session id, must be the same as used in the fraud protection fingerprint. Can be used over multiple payments in the same session"
    }
    "returnUrl": {
      "type": "string",
      "description": "Absolute url where the payer will be redirected to after `complete`/`failure`/`cancel` of the payment"
    },
    "companyName": {
      "type": "string",
      "description": "The companyName will be used as label for payer of the payment in the checkout"
    },
    "logo": {
      "type": "string",
      "description": "Absolute url to a png file, size 190x100px, which will be used as images for the payer of the payment checkout"
    },
    "autoCapture": {
      "type": "boolean",
      "description": "Optional toggle to decide whether the payment will automatically be captured"
    },
    "payer": {
      "type": "object",
      "description": "Payer info provided by your system",
      "properties": {
        "id": {
          "type": "string",
          "description": "Payer ID"
        },
        "firstName": {
          "type": "string",
          "description": "Payer firstname"
        },
        "lastName": {
          "type": "string",
          "description": "Payer lastname"
        },
        "street": {
          "type": "string",
          "description": "Payer street"
        },
        "city": {
          "type": "string",
          "description": "Payer city"
        },
        "zipcode": {
          "type": "string",
          "description": "Payer zipcode"
        },
        "phone": {
          "type": "string",
          "description": "Payer full phone number, starting with country code (+31) (E.164 format)"
        },
        "email": {
          "type": "string",
          "description": "Payer email address"
        },
        "country": {
          "type": "string",
          "description": "Country code 2 characters uppercase (ISO 3166-1 alpha2)"
        },
        "ipAddress": {
          "type": "string",
          "description": "Payer IP address of it's current session"
        },
        "language": {
          "type": "string",
          "description": "Payer Language code 2 characters lowercase (ISO 639-1)"
        },
        "status": {
          "type": "enum",
          "description": "Enum options: `guest`, `registered`, `registered-unconfirmed`"
        },
        "verificationStatus": {
          "type": "string",
          "description": "`identification`: Identification card/passport present, `phone`: verified by phone, `trusted`: trusted with other proof of identification, `otherwise`: otherwise"
        },
        "accountType": {
          "type": "string",
          "description": "Payer account type, Example: `silver`, `gold`, `platinum`"
        },
        "dateRegistration": {
          "type": "datetime",
          "description": "Datetime of payer account registration. Format (ISO 8601) 2016-11-22T11:39:21+0100"
        },
        "dateLastUpdated": {
          "type": "datetime",
          "description": "Datetime of payers last account update. Format (ISO 8601) 2016-11-22T11:39:21+0100"
        },
        "dateFirstPurchase": {
          "type": "datetime",
          "description": "Datetime of payers first purchase. Format (ISO 8601) 2016-11-22T11:39:21+0100"
        },
        "withdrawalHistory": {
          "type": "array",
          "description": "Array of withdrawal transaction history objects",
          "items": {
            "type": "object",
            "description": "Object of the withdrawal transaction history",
            "properties": {
              "datetime": {
                "type": "string",
                "description": "Transaction datetime, Format (ISO 8601) 2016-11-22T11:39:21+0100"
              },
              "id": {
                "type": "string",
                "description": "Transaction ID"
              },
              "description": {
                "type": "string",
                "description": "Transaction description"
              },
              "amount": {
                "type": "integer",
                "description": "Transaction amount in cents"
              }
            },
            "required": [
              "datetime",
              "id",
              "description",
              "amount"
            ]
          }
        },
        "cashBalance": {
          "type": "integer",
          "description": "Current amount of cash balance of the payer in cents"
        },
        "bonusBalance": {
          "type": "integer",
          "description": "Current amount of bonus balance of the payer in cents"
        },
        "openPositionCost": {
          "type": "integer",
          "description": "Current amount of open position cost of the payer in cents"
        },
        "binaryHistory": {
          "type": "array",
          "description": "Array of binary transaction history objects",
          "items": {
            "type": "object",
            "description": "Object of binary transaction history",
            "properties": {
              "datetime": {
                "type": "string",
                "description": "Transaction datetime. Format (ISO 8601) 2016-11-22T11:39:21+0100"
              },
              "id": {
                "type": "string",
                "description": "Transaction ID"
              },
              "description": {
                "type": "string",
                "description": "Transaction description"
              },
              "amount": {
                "type": "string",
                "description": "Transaction amount in cents"
              }
            },
            "required": [
              "datetime",
              "id",
              "description",
              "amount"
            ]
          }
        },
        "forexHistory": {
          "type": "array",
          "description": "Array of forex transaction history objects",
          "items": {
            "type": "object",
            "description": "Object of forex transaction history",
            "properties": {
              "datetime": {
                "type": "string",
                "description": "Transaction datetime. Format (ISO 8601) 2016-11-22T11:39:21+0100"
              },
              "id": {
                "type": "string",
                "description": "Transaction ID"
              },
              "description": {
                "type": "string",
                "description": "Transaction description"
              },
              "amount": {
                "type": "string",
                "description": "Transaction amount in cents"
              }
            },
            "required": [
              "datetime",
              "id",
              "description",
              "amount"
            ]
          }
        }
      },
      "required": [
        "id",
        "firstName",
        "lastName",
        "street",
        "city",
        "zipcode",
        "phone",
        "email",
        "country",
        "ipAddress",
        "language",
        "status",
        "verificationStatus",
        "accountType",
        "dateRegistration",
        "dateLastUpdated",
        "dateFirstPurchase",
        "withdrawalHistory",
        "cashBalance",
        "bonusBalance",
        "openPositionCost",
        "binaryHistory",
        "forexHistory"
      ]
    },
    "transaction": {
      "type": "object",
      "description": "Transaction data",
      "properties": {
        "reference": {
          "type": "string",
          "description": "Your transaction reference shown to the payer"
        },
        "currency": {
          "type": "string",
          "description": "Currency code 3 characters format (ISO 4217)"
        },
        "amount": {
          "type": "integer",
          "description": "Amount in cents"
        },
        "description": {
          "type": "string",
          "description": "Description of the transaction"
        },
        "lines": {
          "type": "array",
          "description": "Array of lines objects",
          "items": {
            "type": "object",
            "description": "Object of transaction line",
            "properties": {
              "name": {
                "type": "string",
                "description": "Item name"
              },
              "description": {
                "type": "string",
                "description": "Item description"
              },
              "quantity": {
                "type": "integer",
                "description": "Quantity of transaction item"
              },
              "amount": {
                "type": "integer",
                "description": "Amount in cents for a one quantity"
              }
            },
            "required": [
              "name",
              "description",
              "quantity",
              "amount"
            ]
          }
        }
      },
      "required": [
        "reference",
        "currency",
        "amount",
        "description",
        "lines"
      ]
    }
  },
  "required": [
    "id",
    "returnUrl",
    "companyName",
    "logo",
    "autoCapture",
    "payer",
    "transaction"
  ]
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": "7c8cca84-5745-4f2c-9701-8a685e544986",
  "amount": 2000,
  "currency": "EUR",
  "timestamp": "2017-02-06T15:24:39+0000",
  "status": "accepted",
  "paymentMethod": "paypal",
  "payerUrl": "Absolute checkoutUrl to redirect the payer to"
}

Common payment requests ¶

Get payment-methods ¶

Returns a list of active payment methods for your account as a key:value pair.

The ideal key contains a list with issuer ids for the create checkout payment call

Get payment-methods
GET`/api/payment-methods`

Example URI

GET https://riskfreecheckout.com/api/payment-methods

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "sofort": "sofort",
  "paypal": "paypal",
  "creditcard": "creditcard",
  "ideal": {
    "INGBNL2A": "Issuer Simulation V3 - ING",
    "RABONL2U": "Issuer Simulation V3 - RABO"
  }
}

Get payment ¶

Get payment
GET`/api/status/{id}`

Example URI

GET https://riskfreecheckout.com/api/status/id

URI Parameters

HideShow

id: string (required)

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": "7c8cca84-5745-4f2c-9701-8a685e544986",
  "createTime": "2017-02-06T15:20:16+0000",
  "timestamp": "2017-02-06T15:24:39+0000",
  "status": "captured"
}

Refund payment ¶

Refund payment
POST`/api/refund`

Example URI

POST https://riskfreecheckout.com/api/refund

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "id": "31e5fa51-2475-455d-b0ad-5febd25434c5",
  "amount": 1000,
  "currentAmount": 5000
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Require UUID v4"
    },
    "amount": {
      "type": "integer",
      "description": "(Optional) Amount in cents. If amount is set we do a `Partial` refund else we do a `Full` refund of the payment amount"
    },
    "currentAmount": {
      "type": "integer",
      "description": "(Optional) Current amount in cents. If amount is set this field is mandatory and should be the current balance of the payment (payment amount minus refunded amounts)"
    }
  },
  "required": [
    "id"
  ]
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": "e9517b61-0608-4b22-b313-1d13aa5856bf",
  "createTime": "2017-02-06T15:20:16+0000",
  "timestamp": "2017-02-06T15:24:39+0000",
  "status": "refunded",
  "amount": 2000,
  "refundAmount": 1000
}

Overview ¶

Endpoint usage ¶

Acquire access token ¶

Request access token ¶

Create new Access tokenGET/oauth/v2/token?client_id={clientId}&client_secret={clientSecret}&grant_type=client_credentials

Example URI

Headers

Body

Create Checkout payment ¶

Forex checkout payment ¶

Forex checkout paymentPOST/api/checkout

Example URI

Headers

Body

Schema

Headers

Body

Create Direct payment ¶

Forex checkout payment ¶

Forex direct paymentPOST/api/authorize

Example URI

Headers

Body

Schema

Headers

Body

Common payment requests ¶

Get payment-methods ¶

Get payment-methodsGET/api/payment-methods

Example URI

Headers

Body

Get payment ¶

Get paymentGET/api/status/{id}

Example URI

Headers

Body

Refund payment ¶

Refund paymentPOST/api/refund

Example URI

Headers

Body

Schema

Headers

Body

Create new Access token
GET`/oauth/v2/token?client_id={clientId}&client_secret={clientSecret}&grant_type=client_credentials`

Forex checkout payment
POST`/api/checkout`

Forex direct payment
POST`/api/authorize`

Get payment-methods
GET`/api/payment-methods`

Get payment
GET`/api/status/{id}`

Refund payment
POST`/api/refund`