summaryrefslogtreecommitdiff
path: root/wireformats.rst
blob: 4e15493000b13c1afe3588214be43793be0eb2e1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
.. _wireformats:

Wire Transfer Formats
=====================

A wire transfer is essential for the exchange to transfer funds into a merchant's
account upon a successful deposit (see :ref:`deposit request <deposit>`).  The
merchant has to include the necessary information for the exchange to initiate the
wire transfer.

The information required for wire transfer depends on the type of wire transfer
used.  Since the wire transfers differ for each region, we document here the
ones currently supported by the exchange.

TEST
----

The TEST wire format is used for testing and for integration with Taler's
simple "bank" system which in the future might be useful to setup a bank
for a local / regional currency or accounting system.  Using the TEST
wire format in combination with the Taler's bank, it is thus possible to
fully test the Taler system without using "real" currencies.  The wire
format for "TEST" is very simple, in that it only specifies an account
number in a field "account_number" and the URI of the bank:

  * `type`: the string constant `"test"`
  * `bank_uri`: the URI of the bank (starting with `http://` or `https://`)
  * `account_number`: the number of the account at the bank

The account number given must be a positive 53-bit integer.
Additional fields may be present, but are not required.

Note that a particular exchange is usually only supporting one
particular bank with the "TEST" wire format, so it is not possible for
a merchant with an account at a different bank to use "TEST" to
transfer funds across banks. After all, this is for testing and not
for real banking.

SEPA
----

The Single Euro Payments Area (SEPA) [#sepa]_ is a regulation for electronic
payments.  Since its adoption in 2012, all of the banks in the Eurozone and some
banks in other countries adhere to this standard for sending and receiving
payments.  Note that the currency of the transfer will (currently) always be *EURO*.  In
case the receiving account is in a currency other than EURO, the receiving bank
may covert the amount into that currency; currency exchange charges may be
levied by the receiving bank.

For the merchant to receive deposits through SEPA, the deposit request must
contain a JSON object with the following fields:

  .. The following are taken from Page 33, SEPA_SCT.pdf .

  * `type`: the string constant `"sepa"`
  * `iban`: the International Bank Account Number (IBAN) of the account of the beneficiary
  * `name`: the name of the beneficiary
  * `bic`: the Bank Identification Code (BIC) code of the beneficiary's bank
  * `salt`: random salt (used to make brute-forcing the hash harder)

The JSON object may optionally contain:
  * `address`: the address of the Beneficiary

The implementation of the SEPA plugin is currently incomplete.  Specifically, we need a working implementation of `libebics` which is a sub-project trying to implement the EBICS [#ebics]_ standard.
    
.. [#sepa] SEPA - Single Euro Payments Area:
           http://www.ecb.europa.eu/paym/sepa/html/index.en.html
.. [#ebics] EBCIS - European Banking Computer Interface Standard
          http://www.ebics.org/