NAV Navbar
shell
  • Introduction
  • Authentication
  • Logged User
  • Transactions
  • Charging a Payment
  • Errors
  • Introduction

    Welcome to the xpay API! You can use our API to access xpay API endpoints.

    You can use our end points in a Shell and Python! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

    This API documentation page was created with Slate.

    Authentication

    Get an authentication token

    To authorize, use this code:

    # With shell, you can just pass the correct header with each request
    curl -X POST \
      -H "Content-Type: application/json" \
      -d '{ "email":"$EMAIL", "password":"$PASSWORD" }' \
      https://$HOST/api/v1/auth/login/
    

    Make sure to replace $HOST with the right environment and $EMAIL and $PASSWORD with your credentials.

    The above command returns JSON structured like this:

    {
      "key": "meowmeowmeow",
    }
    

    Description

    HTTP Request

    POST api/v1/auth/login/

    Query Parameters

    Parameter Type Required Description
    email String true Email of the user to be logged in.
    password String true Password of the user to be logged in.

    Response

    Field Type Description
    token String The authentication token.

    Errors

    Response Code Field Description

    Using the authentication token

    xpay requires an email and a password to allow access to the API. When you are logged in, you will get an authentication token.

    xpay expects for the token to be included in all API requests to the server in a header that looks like the following:

    Authorization: Token $TOKEN

    Logged User

    These endpoints provide useful facilities to retrieve and change user main information. For all the endpoints an Active User must be logged in with a valid token.

    Logged User Info

    # Get / Retrieve the all the information of a logged user
    curl https://$HOST/api/v1/users/
      -H "Authorization: Token $TOKEN"
    

    Make sure to replace $HOST with the right environment and $TOKEN with your authentication token.

    The above command returns JSON structured like this:

    {
        "user_info": {
            "id": 49,
            "username": "johndoe@mail.com",
            "first_name": "John",
            "last_name": "Doe",
            "email": "johndoe@mail.com",
            "is_active": true,
            "twofa": true,
            "manager": true,
            "groups": [
                "Commerce Admin"
            ]
        },
        "commerce": {
            "id": 31,
            "email": "commerce@mail.com",
            "name": "Commerce name",
            "dni": "7515477985",
            "active": false,
            "status": "verifying",
            "fiat_withdraw": false,
            "document_type": {
                "name": "N.I.T.",
                "country": "CO"
            }
        }
    }
    

    Description

    This Url Retrieve all the information from a logged user. It is not required any other permissions or authentications than a valid token. This Endpoint retrieve all the information related to a User, No matter what type of user is.

    HTTP Request

    GET api/v1/users/

    To retrieve all the detailed information of a User the following requirement must be satisfied:

    Response

    Field Type Description
    user dict a dictionary with all the information from a User model.
    profile dict a dictionary with all the information related to the User Profile
    manager dict a dictionary with all the information related to the Manager model if the user is a Manager
    commercemanager dict a dictionary with all the information related to the a CommerceManager if the user is a CommerceManager
    commerceuser dict a dictionary with all the information related to the a CommerceUser if the user is a CommerceUser
    groups list A list with the Groups where the user have Authentication and Athorizations, to perform tasks and retrieve information.

    Errors

    Response Code Field Type
    2002 invalid - the request is not valid, a field or param has an invalid value
    3003 not_authenticated - the user that is making the request don't have the required permissions process the request.
    3004 unkown error - an internal error ocurr on server side

    Change User Password

    # Change the password of a user
    curl -X POST \
      -H "Authorization: Token $TOKEN" \
      -F "old_password=$OLD_PASSWORD" \
      -F "new_password=$NEW_PASSWORD" \
      -F "new_password_confirmation=$NEW_PASSWORD" \
      https://$HOST/api/v1/password/
    

    Make sure to replace $HOST with the right environment and $TOKEN, $OLD_PASSWORD, and $NEW_PASSWORD with the right values.

    The above command returns JSON structured like this:

    {
        "message": "Password Changed"
    }
    

    Description

    This Endpoint change The password of a user if all the condition and requirements are satisfied..

    HTTP Request

    PUT "api/v1/password/"

    To change a password, the next requirements must be satisfied:

    Query Params

    Parameter Type Required Description
    old_password String true the value of the old password
    new_password String true the value for the new password
    new_password_confirmation String true the confirmation value for the new password

    Response

    Field Type Description
    message string a successful message if the request is processed with no error

    Errors

    Response Code Field Type
    2002 invalid - the request is not valid, a field or param has an invalid value
    3003 not_authenticated - the user that is making the request don't have the required permissions process the request.
    3004 unknown error - an internal error occurred on server side
    5001 This Field can't be empty
    5002 This field is required
    5003 The password is too short < 8 chars
    5004 The password is too long > 52 chars
    5020 password must have at least one lower case
    5021 password must have at least one upper case
    5022 password must have at least one number
    5023 password must have at least one of these symbols: %&*#@!¡?¿+$_-

    Transactions

    Get Transactions

    Any manager or a terminal user can retrieve transactions. The shown result changes depending on what kind of user make the request.

    When the request is made by a terminal user, the result contains the fields shown in the following table:

    Field Type Description
    id Number Id of the transaction.
    amount_to_change Number Amount which receive the commerce.
    currency_to_change String Currency which receive the commerce.
    string_amount_to_change String A string representation of amount_to_change.
    amount_to_paid Number Amount which the customer will pay to the commerce.
    currency_to_paid String Currency which the customer will pay to the commerce.
    string_amount_to_paid String A string representation of amount_to_paid.
    commission Number Amount of the commission to xpay.
    fiat_withdraw Integer Percentage to get in a fiat currency in the exchange.
    string_fiat_withdraw String A string representation of fiat_withdraw.
    string_commission String A string representation of commission.
    status String Status of the transaction.
    transaction_status_code Number Numeric value associated to the status.
    date Datetime Creation date of the transaction.
    wallet String Token of the wallet to make the deposit.
    waiting_time Number Limit time to make the deposit.
    waiting_time_unit String Time unit of waiting_time.
    string_waiting_time String A string representation of waiting_time.
    callback String The URL given by the user.

    By the other hand, when the request is made by a manager, it is shown the information of the user that created the transaction.

    Transaction Status

    A transaction has a status with an associated numeric value, they are described in the following table:

    status transaction_status_code description
    'initial' 0 The transaction is just created.
    'verifying' 1 The payment is being verified.
    'adjustment' 2 The payment is being readjusted.
    'sending' 3 Expecting the payment.
    'approved' 4 The payment has been approved.
    'rejected' 5 The payment has been rejected.
    'canceled' 6 The transaction has been canceled by the user.

    Get a Transaction by id

    curl \
      -H "Authorization: Token $TOKEN" \
      https://$HOST/api/v1/transactions/$ID/
    

    Make sure to replace $HOST with the right environment, $TOKEN with your credentials, and $ID for the number of the transaction that you want to get.

    The above command returns JSON structured like this for a single transaction (example $ID = 1).

    {
      "id":1,
      "amount_to_change":"100000.00",
      "currency_to_change":"COC",
      "string_amount_to_change":"100000.00 COC",
      "amount_to_paid":"0.00400000",
      "currency_to_paid":"BTC",
      "string_amount_to_paid":"0.00400000 BTC",
      "commission":"0.08000000",
      "string_commission":"0.08000000 BTC",
      "fiat_withdraw": "100",
      "string_fiat_withdraw": "100 %",
      "status":"approved",
      "transaction_status_code":3,
      "date":"2018-09-29T19:16:41.705604Z",
      "wallet":"meowmeowmeow",
      "waiting_time":"1200.00",
      "waiting_time_unit":"seconds",
      "string_waiting_time":"1200.00 seconds",
      "callback": null
    }
    

    This endpoint retrieves a transaction with the given id

    HTTP Request

    GET api/v1/transactions/:id/

    Query Parameters

    Parameter Type Required Description
    id Number true The id of the transaction.

    Response

    The successful response is the structure shown above.

    Errors

    Response Code Field Description
    401 Unauthorized 3001 id The user is not authorized to get the transaction.

    Get all Transactions

    curl \
      -H "Authorization: Token $TOKEN" \
      https://$HOST/api/v1/transactions/
    

    Make sure to replace $HOST with the right environment and $TOKEN with your credentials,

    The above command returns JSON structured like this for a single transactions.

    
    [
      {
        "id":1,
        "amount_to_change":"100000.00",
        "currency_to_change":"COC",
        "string_amount_to_change":"100000.00 COC",
        "amount_to_paid":"0.00400000",
        "currency_to_paid":"BTC",
        "string_amount_to_paid":"0.00400000 BTC",
        "commission":"0.08000000",
        "string_commission":"0.08000000 BTC",
        "fiat_withdraw": "100",
        "string_fiat_withdraw": "100 %",
        "status":"approved",
        "transaction_status_code":3,
        "date":"2018-09-29T19:16:41.705604Z",
        "wallet":"meowmeowmeow",
        "waiting_time":"1200.00",
        "waiting_time_unit":"seconds",
        "string_waiting_time":"1200.00 seconds",
        "callback": null
      },
      {
        "id":2,
        "amount_to_change":"10000.00",
        "currency_to_change":"COC",
        "string_amount_to_change":"10000.00 COC",
        "amount_to_paid":"0.00049617",
        "currency_to_paid":"BTC",
        "string_amount_to_paid":"0.00049617 BTC",
        "commission":"0.08000000",
        "string_commission":"0.08000000 BTC",
        "fiat_withdraw": "100",
        "string_fiat_withdraw": "100 %",
        "status":"canceled",
        "transaction_status_code":6,
        "date":"2018-10-19T20:46:51.668538Z",
        "wallet":"meowmeowmeow",
        "waiting_time":"1200.00",
        "waiting_time_unit":"seconds",
        "string_waiting_time":"1200.00 seconds",
        "callback":null
      }
    ]
    

    This endpoint retrieves either all transactions created by the requester user (if the user is a terminal) or all transactions created by users from the commerce where belongs the requester (if the user is a manager).

    HTTP Request

    GET api/v1/transactions/?status=:status_1,:status_2,...,:status_n&from=:date_from&to=:date_to&user=:user_id

    Query Parameters

    Optionally, it is possible to filter the result by using filter as query parameters.

    Parameter Type Required Description
    status String false Transaction statuses separated by commas, the valid statuses are shown here.
    from Date false The minimum date of the transactions creation that will be retrieved, it has to be in the format YYYY-MM-DD[+/-hh:mm].
    to Date false The maximum date of the transactions creation that will be retrieved, it has to be in the format YYYY-MM-DD[+/-hh:mm].
    user Number false The id of the user that made the transactions that will be retrieved, only managers may use this filter.

    The date format for the parameters from and to are described as follow:

    Substring Description
    YYYY Four digits representation of the year.
    MM Two digits representation of the month.
    DD Two digits representation of the day

    Optionally, you may set the UTC offset of your timezone in order to retrieve the result based the time in your country. By default this value is set to '+00:00', in other words, the timezone is set to the Greenwich meridian time.

    Response

    The successful response is an array which each element is formed of the structure shown above.

    Errors

    Response Code Field Description
    401 Unauthorized 3002 user The requester is not authorized to filter by user id.
    401 Unauthorized 3003 all The requester is not authorized to list transactions.
    401 Unauthorized 3004 user The requester can not filter by the given user id.
    400 Bad Request 3005 user The selected user to filter does not exist.
    400 Bad Request 3006 status There is an incorrect status value.
    400 Bad Request 3007 from date_from format is not correct.
    400 Bad Request 3008 to date_to format is not correct.
    400 Bad Request 3009 from, to date_from is greater than date_to.

    Create a Transaction Deposit

    curl -X POST \
      -H "Authorization: Token $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"src_currency":"$SRC_CURRENCY",
           "tgt_currency":"$TGT_CURRENCY",
           "amount":$AMOUNT,
           "exchange_id":$ID,
           "callback":"$CALLBACK",
           "fiat_withdraw":$FIAT_WITHDRAW}'
      https://$HOST/api/v1/transactions/
    

    Make sure to replace $HOST with the right environment, $TOKEN with your credentials, and all of the other variables for the values that you need to use.

    The above command returns JSON structured like this:

    {
      "id":1,
      "amount_to_change":"100000.00",
      "currency_to_change":"COC",
      "string_amount_to_change":"100000.00 COC",
      "amount_to_paid":"0.00400000",
      "currency_to_paid":"BTC",
      "string_amount_to_paid":"0.00400000 BTC",
      "commission":"0.08000000",
      "fiat_withdraw": "100",
      "string_fiat_withdraw": "100 %",
      "string_commission":"0.08000000 BTC",
      "status":"sending",
      "transaction_status_code":3,
      "date":"2018-09-29T19:16:41.705604Z",
      "wallet":"meowmeowmeow",
      "waiting_time":"1200.00",
      "waiting_time_unit":"seconds",
      "string_waiting_time":"1200.00 seconds",
      "callback": "https://url/callback/"
    }
    

    This endpoint allows users to ask for a wallet to make a deposit in a given currency.

    HTTP Request

    POST api/v1/transactions/

    Query Parameters

    Parameter Type Required Description
    src_currency String true Crypto currency code to make the payment.
    tgt_currency String true Fiat currency which commerce will receive.
    amount Number true Amount in tgt_currency which commerce will receive.
    exchange_id Number true Id of the exchange platform.
    callback String false An URL to be called when the transaction changes it status.
    fiat_withdraw Integer false Percentage of fiat currency to get in the exchange.

    Response

    The successful response is the structure shown above.

    Errors

    Response Code Field Description
    401 Unauthorized 3010 commerce The commerce is not active
    401 Unauthorized 3011 commerce The commerce has not a document.
    401 Unauthorized 3012 user The requester does not belong to a commerce.
    400 Bad Request 3013 src_currency, tgt_currency, amount, exchange_id Missing some required fields.
    400 Bad Request 3014 callback The callback is not a valid URL.
    400 Bad Request 3015 src_currency The currency is not supported currently.
    400 Bad Request 3016 src_currency The currency is not a crypto currency.
    400 Bad Request 3017 tgt_currency The currency is not supported currently.
    400 Bad Request 3018 tgt_currency The currency is not a fiat currency.
    400 Bad Request 3019 exchange_id The exchange does not exist.
    400 Bad Request 3020 src_currency, tgt_currency The currency is not exchangeable by the exchange platform.
    400 Bad Request 3021 amount Amount is not greater than 0.
    400 Bad Request 3022 exchange There is not exchange connector for the transaction.
    400 Bad Request 3023 amount_to_paid Error computing amount to deposit.
    400 Bad Request 3024 src_currency, tgt_currency, amount There is not market for the transaction.
    400 Bad Request 3025 wallet Error creating the wallet to deposit.

    Cancel a Transaction

    curl -X POST \
      -H "Authorization: Token $TOKEN" \
      https://$HOST/api/v1/transactions/cancel/$ID/
    

    Make sure to replace $HOST with the right environment, $TOKEN with your credentials, and $ID for the number of the transaction that you want to cancel.

    The above command returns JSON structured like this:

    {
      "id":1,
      "amount_to_change":"100000.00",
      "currency_to_change":"COC",
      "string_amount_to_change":"100000.00 COC",
      "amount_to_paid":"0.00400000",
      "currency_to_paid":"BTC",
      "string_amount_to_paid":"0.00400000 BTC",
      "commission":"0.08000000",
      "string_commission":"0.08000000 BTC",
      "fiat_withdraw": "100",
      "string_fiat_withdraw": "100 %",
      "status":"canceled",
      "transaction_status_code":6,
      "date":"2018-09-29T19:16:41.705604Z",
      "wallet":"meowmeowmeow",
      "waiting_time":"1200.00",
      "waiting_time_unit":"seconds",
      "string_waiting_time":"1200.00 seconds",
      "callback": "https://url/callback/"
    }
    

    This endpoint allows users to cancel a transaction. A transaction only may be canceled either by the terminal user that created it or the manager of the commerce associated with the transaction. Moreover the transaction may be canceled only if it is in status 'sending'.

    HTTP Request

    POST api/v1/transactions/cancel/:id/

    Query Parameters

    Parameter Type Required Description
    id Number true The id of the transaction.

    Response

    The successful response is the structure shown above.

    Errors

    Response Code Field Description
    400 Bad Request 3026 id Transaction does not exist.
    400 Bad Request 3027 id Transaction is not in status 'sending'.
    401 Unauthorized 3028 all The requester is not authorized to cancel the transaction.

    Charging a Payment

    The first step to charge a payment is to request for the list of available currencies to receive.

    Available Currencies to Receive

    curl \
      -H "Authorization: Token a8f2f76420676583a738978fa5fb889025819382" \
      https://$HOST/api/v1/transactions/available/currencies/$AMOUNT/$CURRENCY/
    

    Make sure to replace $HOST with the right environment, $TOKEN with your credentials, and $AMOUNT and $CURRENCY for the right values.

    The above command returns JSON structured like this:

    {
      "available_currencies": [
        {
          "exchange": 1,
          "currency": {"code": "ETH", "name": "Ether", "symbol": "ETH"},
          "exchange_amount": "0.022222222222222223"
        },
        {
          "exchange": 1,
          "currency": {"code": "BTC", "name": "Bitcoin", "symbol": "BTC"},
          "exchange_amount": "0.00400000"
        },
        {
          "exchange": 1,
          "currency": {"code": "BCH", "name": "Bitcoin Cash", "symbol": "BCH"},
          "exchange_amount": "0.02857143"
        }
      ],
      "amount": 100000
    }
    

    This endpoint retrieves all currencies that can be exchanged for a given amount of a currency in a country.

    HTTP Request

    GET api/v1/transactions/available/currencies/:amount/:currency/

    Query Parameters

    Parameter Type Required Description
    amount Number true The amount (in local currency) that commerce will get.
    currency String true The currency code for the amount.

    Response

    Field Type Description
    available_currencies Array List of available currencies to exchange
    amount Number Amount to change

    Errors

    Response Code Field Description
    401 Unauthorized 3029 commerce The commerce does not have a document.
    400 Bad Request 3030 currency The currency is not supported currently.
    400 Bad Request 3031 currency The currency is not a fiat currency.

    After getting the list of available currencies to receive, the next step is to create a transaction deposit.

    Errors

    The Kittn API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request is invalid.
    401 Unauthorized -- Your API key is wrong.
    403 Forbidden -- The kitten requested is hidden for administrators only.
    404 Not Found -- The specified kitten could not be found.
    405 Method Not Allowed -- You tried to access a kitten with an invalid method.
    406 Not Acceptable -- You requested a format that isn't json.
    410 Gone -- The kitten requested has been removed from our servers.
    418 I'm a teapot.
    429 Too Many Requests -- You're requesting too many kittens! Slow down!
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

    HTTP Status Codes

    The XPAY API tries at every possible cost to be consistent and coherent with the HTTP status codes, so they keep their original meaning for what they've created.

    A continuación puedes ver un listado de los códigos de estado HTTP más comunes que encontrarás en nuestra API.

    Code Meaning
    200 OK -- Is the standard response for GET and OPTION request types.
    201 Created -- Is the standard response for POST request types that creates a new resource on the API of XPAY
    204 No Content -- Is the standard response for DELETE request type
    400 Bad Request -- Is the standard response for an invalid request
    401 Unauthorized -- Is the standard response when a resource is not public & it only is allowed to be accessed/consume by user with enoght privilges. Usually means that a user does not has an active valid Token.
    403 Forbidden -- Is the standard response when a resource is denied for a user, even when the user is already authenticated.
    404 Not Found -- Is the standard response when a resource is not found on the server
    405 Method Not Allowed -- It is the standard response when trying to access a resource with an HTTP method that is not allowed.
    406 Not Acceptable -- Is the standard response when a request has been made with the header Accept is different of application/json
    413 Request Entity Too Large -- The request of the browser is too long and for that reason the server do not proccess it.
    500 Internal Server Error -- Is the standard response when a server error occurs and can't be solved/resolved by the current user.

    HTTP Allowed Methods.

    Method Use
    OPTIONS Allows to obtaining a list of the a HTTP method accept by a resource.
    GET It is used to retrieve a resource, only readi method
    POST It is used to create a new resource on the server.
    PUT It is used to modify a resource on the server.
    DELETE It is used to delete resource on the server.