apiary.apib

FORMAT: 1A
HOST: https://tokenizer-api.herokuapp.com/

# Mbill Transfer Tokenization Service

# Authorization

We use BASIC HTTP authorization. You should provide access token as HTTP Basic username:

> curl -uAPI_TOKEN https://example.com/

# Transfer Flow

1. Include `https://transfers.mbill.co/tokenizer.js` into your page source and [configure it]() to replace your card container.
2. Your card container will be replaced by a secured iframe that is served from our domain.
3. User inputs card data in iframe and you receive `postMessage` with card token if card data is valid or validation errors.
4. Create transfer using card token.
5. Authenticate transfer via 3-D Secure page or via Lookup code. (To authorize on this steps you must to add transfer token to authorization header)
6. Fetch transfer status.

# TODOs

- card2phone and code2card transfers
- transfer status webhooks

# Group Tokens
## Tokens [/tokens]
### Create Card Token [POST]

Exchange card data with **one-time** token that can be used to create transfers.

Data will be stored in RAM and will be encrypted by AES cbc-128 encryption with HMAC signature.

This token with all relative data is temporary and will be automatically removed in pre-defined time period. Usually **15 minutes**.

+ Request (application/json)
    + Attributes(Card)

+ Response 201 (application/json)
    + Attributes (Response_OK)
        + meta (Response__Meta)
            + code: 201
        + data (CardToken_Full)

# Group Transfer
### Create [POST /transfers]

Initiate a peer-to-peer transfer from `sender` peer credentials to `recipient`'s.

Sender can be:
- `card` - Deprecated. Full card data, including: number, cvv, expiration date.
- `card-token` - Recommended. Token issues in [Create Token](#reference/tokens) endpoint.

Recipient can be: 
- `card-token` - Recommended. Token issues in [Create Token](#reference/tokens) endpoint.
- `card-number`
- `external-id` - whenever you want to send payment that can be claimed later. Currently supports only transfers with a system-generated recipient tokens.

Transfer will be created in one of following statuses:
Status | Description
-------|-------
`authentication` | You need to [authorize transfer](#) with data from `auth` field.
`completed` | Transfer is completed, money is sent to recipients issuing bank.
`processing` | Transfer is processing and should be completed or declined within few seconds.
`declined` | Transfer was declined. Reason could be found in `decline` object.
`waiting_for_claim` | Transfer processing will be continued when recipient will claim it's rights on transaction.

+ Request (application/json)
    + Headers
            
            Authorization: Basic REdSc01wWERDajoK
            
    + Attributes(Transfer)

+ Response 201 (application/json)
    + Attributes (Response_OK)
        + meta (Response__Meta)
            + code: 201
        + data (Transfer_FullWithAuth)

### Get [GET /transfers/{id}]

Read transfer data via it's `id`. Transfer access token must be sent via HTTP Basic Auth in **password** field.

+ Parameters
    + id: 1 (string) - Transfer ID

+ Request (application/json)
    + Headers
    
            Authorization: Basic base64(TRANSFER_TOKEN:)

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + meta (Response__Meta)
        + data (Transfer_FullWithAuth)

### Authentication [POST /transfers/{id}/auth]

#### For 3-D Secure Cards

For 3-D Secure cards you don't need to call this method. 

Instead, client broser should create a `application/x-www-form-urlencoded` HTTP POST request to page specified in `auth.acs_url` response field.

This request should contain following fields:

Request Field | Transfer Field
---|---|---
`PaReq` | `auth.pa_req` | 
`TermUrl` | `auth.terminal_url`
`MD` | `auth.md`

If you want browser to be redirected to a custom page after 3-D Secure page, you can add urlencoded redirect url as URI parameter `arrival` in `TermUrl`, example:

> https://p2y.com.ua/pay2you-ext/Confirm3D/input3d?arrival=https%3A%2F%2Fexample.com%2F%23!%2Fsend%2Fsuccess

#### For Non 3-D Secure Card

OTP code will be sent to a user device. *Usually code is sent via issuing bank in SMS to a phone that is listed in bank, NOT a `recipient.phone` number*. 

This code must be used to auhorize transfer via this method. All unathorized transfer will be declined in about 15 minutes.

+ Parameters
    + id: 1 (string) - Transfer ID

+ Request (application/json)
    + Headers
    
            Authorization: Basic base64(TRANSFER_TOKEN:)
            
    + Attributes(object)
        + code: 3382837 (string) - OTP code that was sent to peer's device.

+ Response 201 (application/json)
    + Attributes (Response_OK)
        + meta (Response__Meta)
        + data (Transfer_Full)
            + status: completed

# Group Claims

### Create [POST /claims]

For transfers in `waiting_for_claim` status (when recipient credential has `external-credential` type) our back-end is waiting for recipient to claim hes right to receive this transfer.

+ Request (application/json)
    + Attributes(Claim)

+ Response 201 (application/json)
    + Attributes (Response_OK)
        + meta (Response__Meta)
          + code: 201 (number)
        + data (Claim_FullWithAuth)

### Get [GET /claims/{id}]

+ Parameters
    + id: 1 (string) - Claim ID

+ Request (application/json)
    + Headers
    
            Authorization: Basic base64(CLAIM_TOKEN:)

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + meta (Response__Meta)
        + data (Claim_FullWithAuth)

### Authentication [POST /claims/{id}/auth]

+ Parameters
    + id: 1 (string) - Claim ID

+ Request (application/json)
    + Headers
    
            Authorization: Basic base64(CLAIM_TOKEN:)
            
    + Attributes(object)
        + code: 3382837 (string) - OTP code that was sent to peer's device.

+ Response 201 (application/json)
    + Attributes (Response_OK)
        + meta (Response__Meta)
        + data (Claim_FullWithTransfer)
            + status: completed

# Data Structures
## Responses
### `Response_Collection`
+ meta (Response__Meta, fixed-type)
+ data (array[], fixed-type)
+ paging (Response__Pagination, fixed-type)

### `Response_OK`
+ meta (Response__Meta, fixed-type)
+ data (object, fixed-type)

### `Response_Error`
+ meta (Response__Meta, fixed-type)
    + code: 400 (number)
+ error (Response__Error, fixed-type)

### `Response__Meta`
+ code: 200 (number) - HTTP response code.
+ url: http://example.com/resource (string) - URL to requested resource.
+ type (enum) - Type of data that is located in `data` attribute.
    + object (string) - `data` attribute is a JSON object.
    + list (string) - `data` attribute is a list.
+ code: 200 (number) - HTTP response code.
+ `idempotency_key`: `idemp-ssjssdjoa8308u0us0` (string, optional) - [Idempotency key](http://docs.apimanifest.apiary.io/#introduction/optional-features/idempotent-requests). Send it trough `X-Idempotency-Key` header.
+ `request_id`: `req-adasdoijasdojsda` (string) - [Request ID](http://docs.apimanifest.apiary.io/#introduction/interacting-with-api/request-id). Send it with `X-Request-ID` header.

### `Response__Error`
+ type: type_atom (string) - Atom that represents error type.
+ message: Error description (string) - Human-readable error message. This is for developers, not end-users.

### `Response__Error_DuplicateEntity`
+ type: `object_already_exists` (string) - Atom that represents error type.
+ message: This API already exists (string) - Human-readable error message. This is for developers, not end-users.

### `Response__Error_ValidationFailed`
+ type: validation_failed (string) - type of an error.
+ message: Validation failed. You can find validators description at our API Manifest: http://docs.apimanifest.apiary.io/#introduction/interacting-with-api/errors. (string)
+ invalid (array)
    + `entry_type`: `json_data_proprty` (string) - Type of error.
    + entry: $.cvv (string) - JSON Path to an invalid property.
    + rules (array)
        + rule: required (string) - String constant that represents validation rule type. List of all types can be found in [API Manifest](http://docs.apimanifest.apiary.io/#introduction/interacting-with-api/errors).
        + params (array) - Validation Parameters.

### `Response__Pagination`
+ limit: 20 (number) - A limit on the number of objects to be returned, between 1 and 100. Default: 50.
+ cursors (object)
    + `starting_after`: 56c31536a60ad644060041af (string) - A cursor for use in pagination. An object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
    + `ending_before`: 56c31536a60ad644060041aa (string) - A cursor for use in pagination. An object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
+ size: 1000 (number) - Total number of objects in collection.
+ has_more: false (boolean) - Is this collection have more data to load in the same style as last request loaded it.

## Cards
### `Card`
+ type: card (string)
+ number: 5591587543706253 (string) - Card number.
+ expiration_month: 01 (string) - Card expiration month with leading zero.
+ expiration_year: 2020 (string) - Card expiration year in YYYY format.
+ cvv: 160 (string) - CVV/CVC code.

### `CardNumber`
+ type: `card-number` (string)
+ number: 5591587543706253 (string) - Card number.

### `CardToken`
+ type: `card-token` (string) - Type. Simplifies futher requests that require it.
+ token: `card-token-6253-8a6985e8247a194c58872d85d5ffad05742679fe` (string) - Token that can be used to create transfer with this card. Followed by last 4 digits from card number.

### `CardToken_Full`
+ Include CardToken
+ `token_expires_at`: `2016-10-29T17:35:28.274477Z` (string) - ISO datetime that signals when token will be expired.

### `ExternalCredential`
+ type: `external-credential` (string)
+ id: my_id (string) - Any ID that is relevant to an external system that will complete this transfer.
+ metadata (object) - Metadata object that can be used by your system to store additional recipients credential details.

## Peers
### Peer
+ phone: +380631112233 (string, optional) - Peer phone number.
+ email: smith@example.com (string, optional) - Peer's email.

### `Peer_Sender`
+ Include Peer
+ One Of
    + credential (Card)
    + credential (CardToken)
    
### `Peer_Recipient`
+ Include Peer
+ One Of
    + credential (CardNumber)
    + credential (CardToken)
    + credential (ExternalCredential)

## Transfers
### Transfer
+ amount: 1000 (number) - Transfer amount.
+ fee: 10 (number) - Transfer fee.
+ description: some content (string, optional) - Transfer description
+ metadata (object, optional) - Metadata for transfer. Can store any keys and values that match [specification](http://docs.apimanifest.apiary.io/#introduction/optional-features/metadata).
+ sender (Peer_Sender)
+ recipient (Peer_Recipient)

### `Transfer_Full`
+ id: 1 (string) - Transfer ID that can be used to fetch it later.
+ external_id: 29384 (string) - ID generated by our transfer processing partner.
+ status: authentication (enum) - Transfer status.
    + authentication
    + waiting_for_claim
    + processing
    + completed
    + declined
+ Include Transfer
+ sender (Peer)
    + One Of
        + credential (Card)
        + credential (CardToken_Full)
+ recipient (Peer)
    + One Of
        + credential (CardNumber)
        + credential (CardToken_Full)
        + credential (ExternalCredential)
+ token: `transfer-token-70eb3c2b-9ef0-41b9-989b-0d4bf1d10831` (string) - Access token that can be used to fetch transfer later.
+ `token_expires_at`: `2016-10-18T13:50:40.54502Z` (string) - ISO datetime that signals when token will be expired.
+ updated_at: `2016-10-18T13:50:39.677992` (string) - ISO datetime when there was last change in transfer.
+ created_at: `2016-10-18T13:50:39.677992` - ISO datetime when transfer was created.

### `Transfer_FullWithAuth`
+ Include Transfer_Full
+ One Of
    + auth (Transfer__Auth_3DS)
    + auth (Transfer__Auth_Lookup)

### `Transfer__Auth_3DS`
+ type: `3d-secure` (string) - Type of authentication.
+ acs_url
+ md
+ pa_req
+ terminal_url

### `Transfer__Auth_Lookup`
+ type: `lookup-code` (string) - Type of authentication.
+ md

## Claims
### Claim
+ id: 1239381 (string) - Claim ID, currently auto-generated and sent to recipient's phone number.
+ One Of
    + credential (CardNumber)
    + credential (CardToken_Full)

### `Claim_Full`
+ Include Claim
+ status (enum) - Claim status
    + authentication
    + processing
    + completed
    + declined
+ token: `claim-token-70eb3c2b-9ef0-41b9-989b-0d4bf1d10831` (string) - Access token that can be used to fetch claim later.
+ `token_expires_at`: `2016-10-18T13:50:40.54502Z` (string) - ISO datetime that signals when token will be expired.
+ updated_at: `2016-10-18T13:50:39.677992` (string) - ISO datetime when there was last change in claim.
+ created_at: `2016-10-18T13:50:39.677992` - ISO datetime when claim was created.

### `Claim_FullWithAuth`
+ Include Claim_Full
+ auth (Claim__Auth_Lookup)

### `Claim_FullWithTransfer`
+ Include Claim_Full
+ transfer (object)
    + id: 1 (string) - Transfer ID that can be used to fetch it later.
    + status: processing (enum) - Transfer status.
        + processing
        + completed
        + declined
    + Include Transfer
    + sender (Peer)
        + One Of
            + credential (Card)
            + credential (CardToken_Full)
    + recipient (Peer)
        + One Of
            + credential (ExternalCredential)
    + updated_at: `2016-10-18T13:50:39.677992` (string) - ISO datetime when there was last change in transfer.
    + created_at: `2016-10-18T13:50:39.677992` - ISO datetime when transfer was created.

### `Claim__Auth_Lookup`
+ type: `otp-code` (string) - Type of authentication.