Payments

API version 1.6.0

After having received an invoice a customer is expected to settle it by transferring the total amount including VAT to the client. A single or multiple transfers may occur depending on what is agreed between the client and the customer. The invoice is settled once the full debt expressed by the invoice is transferred. This article describes how money transfers between a client and its customers are implemented in the Profifact service.

Index

Introduction
Creating a payment
1. Request
2. Response

Introduction

The payment model and its relations to other models

The Profifact service implements transfers of funds between a client and its customers through the /payments resource. A single payment object represents a money transfer from a customer to the client or vice versa. A payment is associated with exactly one invoice. If a single payment is received for settling multiple invoices it is up to the client to split them into several payment objects, one for each invoice involved. A payment object stores the payment date, the amount paid and the payment method. The following payment methods are supported:

UNSPECIFIED: The payment method was not known or was not specified when the payment was added. The client is free to use this value for all payments if further distinction between payments is not required.
BANK: Indicates that the payment was made using a bank transfer. This includes iDEAL payments.
CASH: Indicates that the payment was made by transferring bank notes or coins.
PIN: Indicates that the payment was made using PIN, a Dutch system for debet cards that used a card with a magnetic strip. Even though PIN was replaced on january 1, 2012 by a debit system based on cards with EMV chips, the use of the terms PIN and PIN-code and the associated verb pinnen are still used to refer transactions involving the new EMV cards. Profifact follows that practice by using the payment method PIN to indicate transfers involving bank cards.
CREDITCARD: Indicates that the payment was made using a credit card. For Dutch payments this does not include bank cards (see payment method PIN).
DIRECTDEBIT: Indicates that the payment was collected from the customer using direct debit.
PRIVATE: Indicates that the payment was made through a private bank account.
CLEARED: Indicates that the payment was added to cancel or clear a payment obligation. Using this payment method allows an invoice to be finalized without actually receiving payment. This method should be used, for example, when an invoice is (partially) reversed. The reversed amount is not paid by the customer and by adding a payment with method CLEARED the invoice can progress to status PAID after which it will no longer show up as unsettled. This method may also be used for settling invoice reversals if no transfers of funds have occurred.

Creating a payment

A new payment can be created by sending an HTTP POST request to /customers. The request body must contain values for at least the mandatory payment properties encoded in the content type indicated by the client through the Content-Type header. Currently only JSON encoded data is supported.

Request

HTTP POST requests to /payments are validated before a payment is added. Valid requests must provide valid values for the mandatory fields listed in the table below. If specified, values for optional fields must be valid as well. See the section on data types for an explanation of property data types.

Name	Type	Valid values	Description
invoiceId	int		The unique ID of the invoice to add the new payment to.
date	date		The date of the payment.
amount	decimal		The amount paid. Negative values indicate reverse payments (i.e. payments by the client to the customer). Zero payments are allowed.
method	string	UNSPECIFIED, BANK, CASH, PIN, CREDITCARD, DIRECTDEBIT or PRIVATE	One of the payment methods defined in the introduction.

Examples


            POST /payments HTTP/1.1

            { "invoiceId": 1001778, "date": "2016-07-11", "amount": 750.0, "method": "BANK" }

Response

The Profifact server may send any of the status codes defined in response status codes in response to an incoming request. For a valid request HTTP status 201 Created is returned and the response body contains a Payment object whose members are defined in the following table:

Name	Type	Description
id	int	The unique ID of the payment assigned by Profifact.
invoiceId	int	The unique ID of the invoice to which the payment was added.
date	date	The date of the payment.
amount	decimal	The amount paid. Negative values indicate reverse payments (i.e. payments by the client to the customer). Zero payments are allowed.
method	string	The payment method of the payment as defined in the introduction.