logo
Find anything /
SDK Documentation Sign In

Introduction

YouCan Pay API allows you to integrate your application with the various services that YouCan Pay offers such as:

  • Processing payments
  • Processing transfers
  • Processing invoices

It is a REST API, accepts form-encoded or JSON-encoded request bodies, and returns JSON-encoded responses with structured resource responses. It also uses standard HTTP status codes to indicate success or failure of the request.

JUST GETTING STARTED ?

If you're interested in implementing YouCan Pay as a payment provider, you can use the following guide to get started.

Errors

YouCan Pay uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with YouCan Pay's servers (these are rare). Some 4xx errors could be handled programmatically.

Errors


error string

A human-readable message providing more details about the error.


Validation Error object

Contains children

Child attributes

Validation Error.message string

A human-readable message providing more details about the error.


Validation Error.fields object

It and object contains all the fields that have a validation. the fields come as an array of messages

200 - OK
Everything worked as expected.
201 - Created
The object has been successfully created.
400 - Bad Request
The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized
No valid API key provided.
422 - Unprocessable Entity
Validation error.
404 - Not Found
The requested resource doesn't exist.
500 - Server Errors
Something went wrong on YouCan Pay's end. (These are rare.)

Payment

This section details operations related to tokenizing and processing payments.

Tokenize payment

This endpoint is for generating a payment token that works on all payment gateways.

Body parameters


pri_key required

Merchant account's private key


order_id required

The order ID corresponding to the transaction, used to track which order the transaction is for on your store.


amount required

Integer representing the payment amount in minor units


currency required

ISO-4217 currency code.


metadata optional

An object containing data related to the transaction. We use this for many things including monitoring and fraud prevention. The schema is completely


customer optional

An object containing customer data

Returns


Returns a token ID that can later be used to complete the payment.

post /tokenize
    
      $ curl --location --request POST 'https://youcanpay.com/api/tokenize' \
  --header 'Accept: application/json' \
  --form 'amount="500"' \
  --form 'currency="MAD"' \
  --form 'pri_key="pri_key_for_test"' \
  --form 'order_id="12"' \
  --form 'metadata[cart.id]="uuid"' \
  --form 'metadata[type]="checkout"'
    
  
The response object
    
      {
    "transaction_id": "840f1c8a-6554-45d5-a1ad-f8a48f928dcf",
    "token": "cp500014337"
}
    
  

CashPlus Gateway

Process a payment using the CashPlus gateway.

Body parameters


pub_key required

Merchant account's public key.


token_id required

A tokenized payment ID.


payment_method required | array

Payment method information, typically an array containing details about the payment method.


payment_method.type required | string

Type of payment method, should be a string representing the payment method type "card" or "cashplus

Returns


A transaction ID for tracking purposes, and a CashPlus token to use at one of their agencies.

post /cashplus/init
    
      $ curl --location --request POST 'https://youcanpay.com/api/cashplus/init' \
    --form 'pub_key="pub_d8116a60-ece8-4e14-b475-c8d349a5"' \
    --form 'token_id="b7928f2a-c44b-41e2-b82c-cb4654c865b2"' \
    --form 'payment_method[type]="cashplus"'
    
  
The response object
    
      {
    "token": {
      "id": "b7928f2a-c44b-41e2-b82c-cb4654c865b2"
    }
  }
    
  

Card Gateway Sale

Process a payment using a sale operation, this handles authorizing the card and capturing the payment in a single request.

Body parameters


pub_key required

Merchant account's public key.


token_id required

A tokenized payment ID.


credit_card required

The card's number.


card_holder_name required

The card holder's name, used for AVS verification.


cvv required

Card verification value number, usually on the back of the card.


expire_date required

Card expiry date in MM/YY format.


payment_method required | array

Payment method information, typically an array containing details about the payment method.


payment_method.type required | string

Type of payment method, should be a string representing the payment method type "credit_card" or "cashplus"

Returns


A transaction ID if successful. Returns redirect and return URLs if the card has 3DS enabled.

post /pay
    
      $ curl --location --request POST 'https://youcanpay.com/api/pay' \
    --header 'Accept: application/json' \
    --form 'pub_key="pub_d8116a60-ece8-4e14-b475-c8d349a5"' \
    --form 'token_id="1e7862f6-266b-46b1-b550-afcd34f4b76f"' \
    --form 'expire_date="10/24"' \
    --form 'credit_card="4012888888881881"' \
    --form 'cvv="000"' \
    --form 'card_holder_name="John Doe"' \
    --form 'payment_method[type]="credit_card"'
    
  
The response object
    
      {
    "success": true,
    "code": "000",
    "message": "The payment was processed successfully",
    "transaction_id": "f78d4a85-80bf-4405-8aef-9b256ce3f8ac",
    "order_id": "12"
  }
    
  

Account

Accounts are the source of truth used to perform any action while consuming our API. We have provided all necessary account related actions, thus making it easier to exploit different aspects of our system.

Register for an account

As mentioned above, an account is required to consume any endpoint. In order to sign up, you are required to send the object below with your request.

Note: all fields below are required.

Registration


first_name string

First name of the account owner. The first name characters length must be between 3 to 100.


last_name string

First name of the account owner. The last name characters length must be between 3 to 100.


email string

Email of the account owner. Email can be used to access ones YouCan Pay account.


phone string

Phone number of the account owner. Phone number can be used to access ones YouCan Pay account. As of now, we only allow moroccan phone numbers since YouCan Pay isn't open to everyone at the moment.


password string

Password of the account. Password must contain at least 8 characters in length.


password_confirmation string

Password confirmation. Password confirmation must match the password

Returns


Returns a success message when account is created.

post /register
    
      $ curl --location --request POST 'https://youcanpay.com/api/register' \
  --form 'first_name="first_name"' \
  --form 'last_name="last_name"' \
  --form 'email="[email protected]"' \
  --form 'phone="0612345678"' \
  --form 'password="password"' \
  --form 'password_confirmation="password"' \
  --header 'Accept: application/json'
    
  
Response
    
      {
    "message": "Account registered successfully."
}
    
  

Authentication

YouCan Pay relies on JSON Web Tokens for authentication. The token generated must be provided in any request as a bearer token, requests sent with an invalid token are rejected.

Note: your token is key to perform a lot of actions in your account, don't share it with anyone else that has malicious to avoid any unwanted consequence.

Authentication


email_or_phone string

Email or phone account used while creating account.


password string

Password of the account. Password must match the email or phone used to create the account.

Returns


Returns a JSON web token when successful.

post /login
    
      $ curl --location --request POST 'https://youcanpay.com/api/login' \
  --form 'email_or_phone="[email protected]"' \
  --form 'password="password"' \
  --header 'Accept: application/json'
    
  
Response
    
      {
    "token": "eyJ0eXO0OiJKV2GiLCJhbGciOiJIUzI1Nh78.eyJpc3MiOiJodHRwczpcL1wvcGlp0LnRlc3R5b3VjYW4uc2hvcFwvYXBpXC9sb2dpHjssImlhdCI6MTY0MTM3MjEyMywiZXhwIjoxNjQxMzc1NzIzLCJuYmYiOjE2NDEzNzIxMjMsImp0aSI6ImpQaVBLT0lqMHpoksjVR3UiLCJzdWIiOiJkY2Q4MTkzNS05MmQzLTRjMGMtOTBhMS01MjgyYmZjYWU2ODUiLCJwcnYiOiJjN2UxODM1MmVmODFlNmIyZjJkMzk2MDk2ODg1ZjUxNzYwYzIyMTMxIiwis87JLmlyc3RfbmFtZSI6Im91c3NhbWEiLCJsYXN0X25hbWUiOiJGYWRlbCIsImVt88IIjoiZGVja293LmNhc2ltaXJAZXhhbXBsZS5uZXQiLCJwaG9uZSI6Ijc3Ni00NjUtNDYwMyB4NzQzIiwidHlwZSI6Mn0.MC2PSN9VRbm9EBCpGAUVV-G9j8qpWcNFFCwQZ-eercc"
}
    
  

Account information

Retrieves the details of the current account.

Returns


Returns an Account object if the call succeeds. If the account ID does not exist, this call returns an error.

get /me
    
      $ curl --location --request POST 'https://youcanpay.com/api/me' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
Response
    
      {
        "data": {
            "id": "a82cc7b3-b1b6-4b5a-997d-c9c472555e20",
            "identity_id": "df0498a8-bf69-4619-b8d6-1543dd752a9f",
            "first_name": "Doe",
            "last_name": "John",
            "address": ".....",
            "postal_code": "",
            "city": "",
            "region": "",
            "country": "",
            "phone": "",
            "email": "[email protected]",
            "balance": {
            "amount": "779010",
            "currency": "MAD"
        },
            "today_volume": {
            "amount": "0",
            "currency": "MAD"
        },
            "type": 2,
            "display_balance": "MAD 77,901.00",
            "type_text": "BUSINESS"
        }
    }
    
  

Update account

Updates account details by passing the new values. Please note that any parameters not provided are left unchanged.

Authentication


first_name string

First name of the account owner. The first name characters length must be between 3 to 100.


last_name string

Last name of the account owner. The first name characters length must be between 3 to 100.


address string

Address of the account owner.

Returns


Returns a JSON when successful.

put /me
    
      $ curl --location --request PUT 'https://youcanpay.com/api/me' \
    --data-raw '{
      "first_name": "John",
      "last_name": "Doe",
      "address": "....."
    }' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
Response
    
      {
    "message": "Account has been updated successfully"
}
    
  

Update password

Authentication


current_password string

Password of the account. Password must contain at least 8 characters in length.


new_password string

Password confirmation. Password confirmation must match the password.

Returns


Returns a JSON when successful.

put /me/password
    
      $ curl --location --request PUT 'https://youcanpay.com/api/me/password' \
  --data-raw '{
    "current_password": "rBZtmpr6ktMCW3Tn",
    "new_password": "rBZtmpr6ktMCW3Tn"
  }' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
Response
    
      {
    "message": "Account has been updated successfully"
}
    
  

Account stats

Get a list of various stats of your account.

Filter stats


fromDate timestamp

From start date of paid transactions.


toDate timestamp

From end date of paid transactions.


interval enum

The interval days of paid transactions.

Child attributes

interval.today string

Represents paid transactions of today.


interval.yesterday string

Represents paid transactions of yesterday.


interval.thisWeek string

Represents paid transactions of this week.

Returns


Returns an object of stats which contains a collection of paid transactions. If no stats are found, returns an object with an empty paid transactions collection.

get /stats
    
      $ curl --location -g --request GET 'https://youcanpay.com/api/stats' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
Response
    
      {
    "fromDate": "2020-01-01T16:34:08.000000Z",
    "toDate": "2021-12-23T16:34:08.000000Z",
    "totalRevenue": "0",
    "paidTransactionsByDates": [
        {
        "date": "2020-01-01",
        "totalAmount": 0
        },
        ...
    ],
    "acceptanceRatesByDates": [],
    "creditCardsGroupedByBankName": [],
    "creditCardsGroupedBrand": [],
    "creditCardsGroupedByCountry": []
  }
    
  

Refresh auth token

When you initially receive a refresh token it'll have an expiration time which in some cases may be inconvenient if you are performing long time span actions. In that case an endpoint to programmatically refresh your token is available.

post /refresh
    
      $ curl --location --request POST 'https://youcanpay.com/api/refresh' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
Response
    
      {
    "token": "YOUR_TOKEN_eyJpc3MiOiJodHRwOlwvXC9wYXkuZG90c2hvcC5jb21cL2....",
    "expires_in": 3600
}
    
  

Logout

In cases where you want to invalidate your token, you can call this endpoint to logout, by doing so, you can make sure that the token is no longer valid.

post /logout
    
      $ curl --location --request POST 'https://youcanpay.com/api/logout' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
Response
    
      {
    "token": "YOUR_TOKEN_eyJpc3MiOiJodHRwOlwvXC9wYXkuZG90c2hvcC5jb21cL2....",
    "expires_in": 3600
}
    
  

Currencies

Conversion rates

In cases where you want to check currency conversion rates, you can call this endpoint.

get /currency/conversion-rates
    
      $ curl --location -g --request GET 'https://youcanpay.com/api/currency/conversion-rates' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
Response
    
      {
  "base_currency": "USD",
  "conversion_rates": {
    "EUR": 1,
    "GBP": 1.2,
    "MAD": 0.101,
    ...
  }
}
    
  

Transfers

A Transfer object is created when moving a sum between two YouCanPay accounts. You can make a transfer or retrieve a list of transfers related to your account. Each transfer is identified by a random unique ID.

The transfer object

The transfer object


id string

The object's unique identifier.


display_amount string

The transfer's monetary value formatted for display.


message string

A message from the account that initiated the transfer, that may be empty.


is_incoming boolean

Indicates whether the transfer is incoming or outgoing. Is false when your account is the one that initiated the transfer.


transceiver hash

The other account that partook in the transfer.


created_at timestamp

The time that this record of the transfer was first created.

The transfer object
    
      {
    "data": {
      "id": "6ae1bc33-0752-479d-8f76-d7cdee4aa1b4",
      "display_amount": "MAD 5.00",
      "message": "Hello o/",
      "is_incoming": false,
      "created_at": "2021-12-16 15:17:25",
      "transceiver": {
        "data": {
          "id": "268e1200-b2f2-4ea8-a640-d19b58989891",
          "first_name": "Cesar",
          "last_name": "Walter",
          "phone": "537-631-0416",
          "email": "[email protected]",
          "type": 1,
          "type_text": "PERSONAL"
        }
      }
    }
  }
    
  

Create a transfer

To move funds from your YouCanPay account, you must first initiate a transfer. This creates a transfer object if your account has sufficient funds to cover the amount, otherwise you will receive an error.

Create a transfer


amount required

A positive integer in small currency representing how much to transfer.


identifier required

The email or phone number of the YouCanPay account you intend to transfer funds to. Only Moroccan phone numbers (+212) are supported currently.


message optional

A message that will be displayed alongside the transfer.

Returns


Returns a transfer object if the request was successful.

post /transfers
    
      $ curl --location -g --request POST 'https://youcanpay.com/api/transfers' \
  --form 'amount="5"' \
  --form 'identifier="0773777722"' \
  --form 'message="Test"' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
The transfer object
    
      {
    "data": {
      "id": "6ae1bc33-0752-479d-8f76-d7cdee4aa1b4",
      "display_amount": "MAD 5.00",
      "message": "Hello o/",
      "is_incoming": false,
      "created_at": "2021-12-16 15:17:25",
      "transceiver": {
        "data": {
          "id": "268e1200-b2f2-4ea8-a640-d19b58989891",
          "first_name": "Cesar",
          "last_name": "Walter",
          "phone": "537-631-0416",
          "email": "[email protected]",
          "type": 1,
          "type_text": "PERSONAL"
        }
      }
    }
  }
    
  

List all transfers

Returns a paginated list of transfer objects related to the current authenticated account. The list is sorted, with the most recent transfers appearing first by default.

Filter and sort transfers


sort_field enum optional

Field you want to sort by, it can be any value from below:


sort_order string optional

Sorting order, can either be `asc` or `desc`


limit integer optional

Limit query result (when working with pagination)


filters array optional

An array of filter criteria where each entry has the following keys:

Child attributes

filters.value string

The value to compare by


filters.operator string

Comparison operator (=: default, !=, >, <, =>, <=, is, is_not, in)

Returns


Returns a paginated collection of transfer objects. If no transfers are found, returns an empty collection.

get /transfers
    
      $ curl --location -g --request GET 'https://youcanpay.com/api/transfers
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
get /transfers
    
      $ curl --location -g --request GET 'https://youcanpay.com/api/transfers?sort_field=amount&sort_order=asc&filters[0][field]=amount&filters[0][value]=100' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
The transfer object
    
      {
    "data": [
      {
        "id": "0595c470-e87a-48ec-bcd6-c70d17f370ac",
        "display_amount": "MAD 5.00",
        "message": null,
        "is_incoming": false,
        "created_at": "2021-12-10 14:23:58",
        "transceiver": {
          "data": {
            "id": "635bbef8-6468-4d59-894a-501fdba4863b",
            "first_name": "YouCan",
            "last_name": "YouCan",
            "phone": "0676461601",
            "email": "[email protected]",
            "type": 2,
            "type_text": "BUSINESS"
            }
          }
        },
        {...}
    ],
    "meta": {...}
  }
    
  

Recent recipients

Get a list of recent recipients ids you made a transfer to. This can be useful in some cases where you want to have a list of recent account you transferred something to, then have an easy access to those individuals.

Returns


List of recent accounts IDs you made transfers to.

get /transfers/accounts/recent
    
      $ curl --location --request GET 'https://youcanpay.com/api/transfers/accounts/recent' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
Recent accounts
    
      {
    "data": [
      {
        "id": "77710c58-56ba-433d-a390-5fda01e597ee",
        "first_name": "Kane",
        "last_name": "Cantu",
        "phone": "0666666666",
        "email": "[email protected]"
      }
      ...
    ]
  }
    
  

Invoices

Invoices are statements of amounts owed by a customer, and are either generated one-off, or generated periodically from a subscription.

The invoice object

The invoice object


id string

The object's unique identifier.


reference string

A reference to your invoice.


name string

The name of the invoice (product or service) to pay.


display_amount string

The invoice amount displayed with the currency.


status integer

The status of invoice. [0] pending | [1] paid | [-1] expired


is_active boolean

Published or not.


description string

A description of this invoice.


due_by timestamp

This is the payment deadline, if null cannot expire.


account_id string

The identifier of the account which created the invoice.


alias string

A short link used to pay the bill.

The invoice object
    
      {
    "id": "inv_b722cb58-0ba1-428d-99e4-b54ded47d9f6",
    "reference": "tes ref",
    "name": "samir",
    "display_amount": "MAD 100.00",
    "status": 0,
    "is_active": true,
    "description": "Hello this is me saying hello",
    "due_by": null,
    "account_id": "f12f476c-a30d-40f9-9d5d-ba043072aba1",
    "alias": "https://youcanpay.com/i/oTmoxfr"
  }
    
  

Create an invoice

This endpoint creates an invoice ready to be paid.

Create an invoice


reference optional

A reference to your invoice.


name required

The name of the invoice (product or service) to pay.


amount required

The amount to be paid in small integer.


currency required

The currency linked to your amount in capital letters.


contact_option required

The method to use for notifications. [0] Do not send | [1] Email | [2] SMS


description optional

A description that does not exceed 500 characters.


to optional

The phone number or e-mail used for notifications must be linked to the selected option on [contact_option].


active optional

A boolean type can activate or deactivate access to the invoice.


content optional

The content to be sent by the notification.

Returns


Returns an invoice object if the request was successful.

post /invoices
    
      $ curl --location --request POST 'https://youcanpay.com/api/invoices' \
  --form 'reference="tes ref"' \
  --form 'name="samir"' \
  --form 'amount="100"' \
  --form 'currency="MAD"' \
  --form 'contact_option="2"' \
  --form 'description="Hello this is me saying hello"' \
  --form 'to="+212669336603"' \
  --form 'active="1"' \
  --form 'content="test"'
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
The response object
    
      {
    "data": {
      "id": "inv_b722cb58-0ba1-428d-99e4-b54ded47d9f6",
      "reference": "tes ref",
      "name": "samir",
      "display_amount": "MAD 100.00",
      "status": 0,
      "is_active": true,
      "description": "Hello this is me saying hello",
      "due_by": null,
      "account_id": "f12f476c-a30d-40f9-9d5d-ba043072aba1",
      "alias": "https://youcanpay.com/i/oTmoxfr"
    }
  }
    
  

List all invoices

Returns a paginated list of invoice objects related to the current authenticated account. The list is sorted, with the most recent invoices appearing first by default.

Filter and sort invoices


sort_order string optional

Sorting order, can either be `asc` or `desc`


limit integer optional

Limit query result (when working with pagination)


filters array optional

An array of filter criteria where each entry has the following keys:

Returns


Returns a paginated collection of invoice objects. If no invoices are found, returns an empty collection.

get /invoices
    
      $ curl --location -g --request GET 'https://youcanpay.com/api/invoices
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
get /invoices
    
      $ curl --location -g --request GET 'https://youcanpay.com/api/invoices?sort_field=amount&sort_order=asc&filters[0][field]=amount&filters[0][value]=100' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
The invoice object
    
      {
    "data": [
        {
          "id": "inv_094648cb-58f9-7292-8fa5-29ae8189638c",
          "reference": "0000000001",
          "name": "invoice_test",
          "display_amount": "100 MAD",
          "status": 0,
          "is_active": true,
          "description": null,
          "due_by": null,
          "account_id": "8hqb691-c228-4941-bd56-8hkl427snxn",
          "alias": "https://youcanpay.com/i/IO09df4"
        },
        {...}
    ],
    "meta": {...}
  }
    
  

Tokenization

Create token for the given invoice.

post /invoices/tokenize/{invoice_id}
    
      $ curl --location --request POST 'https://youcanpay.com/api/invoices/tokenize/inv_jk7fd0abc-8b2f-4b38-8ee7-fd337cb92f79' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
The response object
    
      {
    "token_id": "067h5klop12-a0f0-4a18-b407-60945cb3ca65",
    "pub_key": "pub_3109gh29sbh-1379-4e64-9a3f-5c8d5bb2"
  }
    
  

Balance History

A Balance History object is created when your YouCan Pay balance is updated (incremented or decremented).

The Balance History object

The balance history object


id string

The object's unique identifier.


account_id string

The YouCan Pay account to which the balance history is attributed.


display_amount string

The balance change's monetary value formatted for display.


causer_type number

An arbitrary value indicating the causer (reason for which balance was altered) as it is stored on our servers. This field can have any of the values below:


causer_type_text string

The string representation of the <code>causer_type</code> property. All possible values can be found above.


causer_id string

The causer id's unique identifier, used in conjunction with <code>causer_type</code> to determine which exact event affected the balance.


created_at timestamp

The time that this record of the transfer was first created.

The balance history object
    
      {
        "id": "70a5e31c-8b00-4fbd-bc0c-1736c6e5304a",
        "account_id": "4ad60bd6-52fa-46cc-ab67-e729fd166922",
        "display_amount": "-50,00 MAD",
        "causer_type": 3,
        "causer_id": "0ff1ca3b-4e50-4056-88d4-b0f822c38376",
        "causer_type_text": "transfer"
    }
    
  

Retrieve balance history

Returns a paginated list of balance history objects related to the current authenticated account. The list is sorted, with the most recent entries appearing first by default.

Filter and sort balance history


sort_field enum optional

Field you want to sort by, it can be any value from below:


sort_order string optional

Sorting order, can either be `asc` or `desc`


limit integer optional

Limit query result (when working with pagination)


filters array optional

An array of filter criteria where each entry has the following keys:

Child attributes

filters.field enum

Field you want to filter by, it can be any value from below:


filters.value string

The value to compare by


filters.operator string

Comparison operator (=: default, !=, >, <, =>, <=, is, is_not, in)

Returns


Returns a paginated collection of balance history objects. If no entries are found, returns an empty collection.

get /balance-history
    
      $ curl --location --request GET 'https://youcanpay.com/api/balance-history \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
The balance history object
    
      {
    "data": [
      {
        "id": "70a5e31c-8b00-4fbd-bc0c-1736c6e5304a",
        "account_id": "4ad60bd6-52fa-46cc-ab67-e729fd166922",
        "display_amount": "-5,00 MAD",
        "causer_type": 3,
        "causer_id": "0ff1ca3b-4e50-4056-88d4-b0f822c38376",
        "causer_type_text": "transfer"
      },
      {...}
    ],
    "meta": {...}
  }
    
  

Withdrawals

Withdrawals as the name conveys, is a representation of the action taken by merchants to pullout their account balance.

The withdrawal object

The withdrawal object


id string

The object's unique identifier.


display_amount object

Withdrawal amount object, containing value and currency


status enum

Status of the withdrawal, possible values are:

Child attributes

status.-1 integer

Pending cancellation


provider_id enum

ID of the gateway used to withdrawal with:

Child attributes

paid_at timestamp

This is the withdrawal date. null if not processed yet.


created_at timestamp

Timestamp when withdrawal when first requested.

The invoice object
    
      {
    "id": "io420po0969-e801-416b-8fe3-0c88f3fff6de",
    "display_amount": {
    "amount": "50000",
    "currency": "MAD"
    },
    "status": 0,
    "status_name": "pending",
    "provider_id": 2,
    "provider_name": "cashplus",
    "paid_at": null,
    "created_at": "2022-01-31 15:11:50"
  }
    
  

Create a withdrawal

Request a withdrawal via your method of choice by providing the desired amount.

Create a withdrawal


payment_method string required

Your preferred withdrawal method. Can either be "bank_account" or "cashplus".


amount integer required

The amount you wish to withdraw. Note that this amount should be more than 100 MAD and can't be greater than your account balance.


withdrawal_bank_account_id string optional

ID of the bank account the withdrawal should process to. This is only required if "payment_method" was set to "bank_account".

Returns


Returns a message in case the withdrawal was requested successfully or if it failed.

post /withdrawals
    
      $ curl --location --request POST 'https://youcanpay.com/api/withdrawals' \
  --form 'payment_method="bank_account"' \
  --form 'amount="500"' \
  --form 'withdrawal_bank_account_id="hj753opsj71-4164-4072-pl209-70740485bc6d"' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
The response object
    
      {
    "message": "Withdrawal requested successfully"
  }
    
  

List all withdrawals

Returns a paginated list of withdrawal objects related to the current authenticated account. The list is sorted, with the most recent withdrawal appearing first by default.

Filter and sort withdrawals


sort_order string optional

Sorting order, can either be `asc` or `desc`


limit integer optional

Limit query result (when working with pagination)


filters array optional

An array of filter criteria where each entry has the following keys:

Returns


Returns a paginated collection of invoice objects. If no invoices are found, returns an empty collection.

get /withdrawals
    
      $ curl --location -g --request GET 'https://youcanpay.com/api/withdrawals
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
get /withdrawals
    
      $ curl --location -g --request GET 'https://youcanpay.com/api/withdrawals?sort_field=amount&sort_order=asc&filters[0][field]=amount&filters[0][value]=100' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
The invoice object
    
      {
    "data": [
        {
          "id": "po83gh78a-e801-416b-p0db3-0c88bsh7mff6de",
          "display_amount": {
          "amount": "50000",
            "currency": "MAD"
          },
          "status": 0,
          "status_name": "pending",
          "provider_id": 2,
          "provider_name": "cashplus",
          "paid_at": null,
          "created_at": "2022-01-31 15:11:50"
        },
        {...}
    ],
    "meta": {...}
  }
    
  

Deposit

Deposit is a way to increment balance using either the CreditCard or CashPlus gateway. The balance is then incremented based on the amount specified when first creating the token.

Tokenization

Create token for deposit. This is the token that'll be used when trying to increment the balance using either gateways.

Tokenization form data


currency string required

Currency tied to the amount. Should be 3 characters long.

post /deposits/tokenize
    
      $ curl --location --request POST 'https://youcanpay.com/api/deposits/tokenize' \
  --form 'amount="500"' \
  --form 'currency="MAD"' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
The response object
    
      {
    "token_id": "gh3pod873-2ca5-40e8-fg62-hk8r23nqx"
  }