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.

Note: If you intend to use the sandbox, you should use the following base URI: https://youcanpay.com/sandbox/api/

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.


success_url optional

This URL is returned when the payment is successfully processed.


error_url optional

This URL is returned when payment is failed.


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 'success_url="https://yourdomain.com/orders-status/success"' \
  --form 'error_url="https://yourdomain.com/orders-status/failed"' \
  --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"
  }
    
  

OAuth

To connect to YouCanPay API, you can use the standard OAuth 2 to get an access token.

Authorization Code

The first step is to redirect to YouCanPay for getting an authorization code. After the seller answer the authorization popup, he will be redirected to the specified redirect uri (https://test.com/) where you can exchange the authorization code for an access token.

Available Scopes : transactions.management, refunds.management, invoices.management, withdrawals.management, account.management

get /oauth/authorize
    
      https://youcanpay.com/oauth/authorize?client_id=your_client_id&redirect_uri=test.com&response_type=code&scope[]=*
    
  
will redirect you to the specified redirect_uri in the request
    
      https://test.com?code=a03849d78399267547d8ac9af639dc61828933791...
    
  

Access Token

To obtain an access token, send a POST request to the OAuth endpoint. Upon successful authentication, the server will respond with an access token that can be used for subsequent API requests.

The OAuth Access Token object


token_type string

The type of token, typically "Bearer".


expires_in integer

The lifetime of the access token in seconds.


access_token string

The access token string as issued by the authorization server.


refresh_token string

The token that can be used to obtain a new access token when the original expires.

post /oauth/token
    
      $ curl --location --request POST 'https://api.youcanpay.com/oauth/token' \
  --form 'client_id="9b2efcdf-4493..."' \
  --form 'client_secret="AGZaZrlI28D..."' \
  --form 'grant_type="authorization_code"' \
  --form 'redirect_uri="https://test.com"' \
  --form 'code="f50200273ca0350c000062e5820..."' \
  --header 'Accept: application/json' \
    
  
The response object
    
      {
    "token_type": "Bearer",
    "expires_in": 31622400,
    "access_token": "eyJ0eXAiOiJKV1QiL...",
    "refresh_token": "def50200fb4a514810b8d8fc32..."
  }
    
  

Refresh token

To request a new access token once the current one expires. This is done by sending a POST request to the token endpoint with the refresh token and necessary credentials. In response, the server will issue a new access token, allowing continued API access without requiring the user to repeatedly authenticate.

post /oauth/token
    
      $ curl --location --request POST 'https://api.youcanpay.com/oauth/token' \
  --form 'client_id="9b2efcdf-4493..."' \
  --form 'client_secret="AGZaZrlI28D..."' \
  --form 'grant_type="refresh_token"' \
  --form 'refresh_token="def50200fb4a514810b8d8fc32..."' \
  --form 'scope=""' \
  --header 'Accept: application/json' \
    
  
The response object
    
      {
    "token_type": "Bearer",
    "expires_in": 31622400,
    "access_token": "eyJ0eXAiOiJKV1QiL...",
    "refresh_token": "def50200fb4a514810b8d8fc32..."
    }
    
  

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.

Account information

Retrieves the details of the current account.

You can add expand param to the request url in case you want to get your identity infos (https://api.youcanpay.com/account/me?expand=identity).

Returns


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

get /account/me
    
      $ curl --location --request POST 'https://api.youcanpay.com/account/me' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
Response
    
      {
        "data": {
            "object": "account",
            "id": "30801ee4-04c2-4a38-8627-91cbffdab749",
            "parent_id": null,
            "first_name": "Customer",
            "last_name": "Customer",
            "phone": "+212699007772",
            "email": "[email protected]",
            "created_at": 1703597019,
            "status": "Active",
            "locale": "en_US",
            "success_url": null,
            "error_url": null,
            "email_verified_at": null,
            "phone_verified_at": null,
            "suspended_at": null,
            "suspension_reason": null,
            "identity": "44b3f6f6-d502-48f2-b1cc-9ee60ca84f6a",
            "funds": {
            "data": {
                "object": "funds",
                "balance": {
                    "amount": "0",
                    "currency": "MAD",
                    "localized": "MAD 0.00"
                },
                "hold": {
                    "amount": "0",
                    "currency": "MAD",
                    "localized": "MAD 0.00"
                }
            }
        }
    }
    
  

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 /account/stats
    
      $ curl --location -g --request GET 'https://api.youcanpay.com/account/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": []
  }
    
  

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://api.youcanpay.com/account/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": {...}
  }
    
  

Transactions

The transaction object

The transaction object


id string

The unique identifier for the transaction.


created_at integer

Timestamp of when the transaction was created.


paid_at integer

Timestamp of when the transaction was paid.


status integer

Numeric status code of the transaction.


status_text string

Textual representation of the transaction status.


customer string

The unique identifier of the customer involved in the transaction.


order_id string

The identifier of the associated order or invoice.


payment_method.type string

Type of the payment method used in the transaction.


payment_method.id string

Unique identifier for the payment method used.


amount.amount string

The total amount of the transaction.


amount.currency string

The currency of the transaction amount.


amount.localized string

The localized representation of the transaction amount.


fees.amount string

The amount of fees associated with the transaction.


fees.currency string

The currency of the transaction fees.


fees.localized string

The localized representation of the transaction fees.


metadata.type string

A metadata type to provide additional information about the transaction.


customer_ip string

IP address of the customer.

get /transactions/0142cd46-5813-4c62-8fd3-081e4a9fb964
    
      $ curl --location -g --request GET 'https://api.youcanpay.com/transactions/0142cd46-5813-4c62-8fd3-081e4a9fb964' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
Response
    
      {
    "data": {
      "object": "transaction",
      "id": "10e7691c-14a2-4936-833b-ec154c817ce9",
      "created_at": 1706515890,
      "paid_at": 1706515899,
      "status": 1,
      "status_text": "paid",
      "customer": "38678dea-d23a-4388-bb78-648892bce85b",
      "order_id": "inv_028ef20c-5065-4515-a0d6-a1c17ff0d53e",
      "payment_method": {
        "type": "credit_card",
        "id": "0fd9bb2c-f14b-411c-bc90-deb73ddaf9ff"
      },
      "amount": {
        "amount": "10000",
        "currency": "MAD",
        "localized": "MAD 100.00"
      },
      "fees": {
        "amount": "690",
        "currency": "MAD",
        "localized": "MAD 6.90"
      },
      "metadata": {
        "type": "youcan_pay.invoice"
      },
      "customer_ip": "192.168.0.113"
    }
  }
    
  

List all transactions

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

Filter and sort transactions


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 transactions objects. If no transactions are found, returns an empty collection.

get /transactions
    
      $ curl --location -g --request GET 'https://api.youcanpay.com/transactions
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
get /transactions
    
      $ curl --location -g --request GET 'https://api.youcanpay.com/transactions?sort_field=amount&sort_order=asc&filters[0][field]=amount&filters[0][value]=10000' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
The invoice object
    
      {
        "data": [
        {
            "object": "transaction",
            "id": "10e7691c-14a2-4936-833b-ec154c817ce9",
            "created_at": 1706515890,
            "paid_at": 1706515899,
            "status": 1,
            "status_text": "paid",
            "customer": "38678dea-d23a-4388-bb78-648892bce85b",
            "order_id": "inv_028ef20c-5065-4515-a0d6-a1c17ff0d53e",
            "payment_method": {
                "type": "credit_card",
                "id": "0fd9bb2c-f14b-411c-bc90-deb73ddaf9ff"
            },
            "amount": {
                "amount": "10000",
                "currency": "MAD",
                "localized": "MAD 100.00"
            },
            "fees": {
                "amount": "690",
                "currency": "MAD",
                "localized": "MAD 6.90"
            },
            "metadata": {
                "type": "youcan_pay.invoice"
            },
            "customer_ip": "192.168.65.1"
        },
        {...},
        "meta": {
            "pagination": {
                "total": 6,
                "count": 6,
                "per_page": 10,
                "current_page": 1,
                "total_pages": 1,
                "links": {}
            }
        }
    }
    
  

Refunds

The refund object

The Refund object


id string

The unique identifier for the refund.


transaction_id string

The unique identifier of the transaction being refunded.


amount.amount string

The total amount of the refund.


amount.currency string

The currency of the refund amount.


currency string

The currency in which the refund was processed.


amount_in_mad.amount string

The refund amount in Moroccan Dirham (MAD).


amount_in_mad.currency string

The currency of the amount in MAD, typically "MAD".


status integer

Numeric status code of the refund.


status_text string

Textual representation of the refund status.


reason integer

Numeric code representing the reason for the refund.


reason_text string

Textual description of the reason for the refund.


created_at integer

Timestamp of when the refund was created.

get /refunds/83cd9f6d-481a-49c4-9cc1-954c065e6063
    
      $ curl --location -g --request GET 'https://api.youcanpay.com/refunds/83cd9f6d-481a-49c4-9cc1-954c065e6063' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
Response
    
      {
        "data": {
        "object": "refunds",
        "id": "83cd9f6d-481a-49c4-9cc1-954c065e6063",
        "transaction_id": "10e7691c-14a2-4936-833b-ec154c817ce9",
        "amount": {
            "amount": "6000",
            "currency": "MAD"
        },
        "currency": "MAD",
        "amount_in_mad": {
            "amount": "6000",
            "currency": "MAD"
        },
        "status": 1,
        "status_text": "succeeded",
        "reason": 1,
        "reason_text": "duplicate",
        "created_at": 1706534112
        }
    }
    
  

List all refunds

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

Filter and sort transactions


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 refunds objects. If no refunds are found, returns an empty collection.

get /refunds
    
      $ curl --location -g --request GET 'https://api.youcanpay.com/refunds
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
get /refunds
    
      $ curl --location -g --request GET 'https://api.youcanpay.com/refunds?sort_field=amount&sort_order=asc&filters[0][field]=amount&filters[0][value]=10000' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
The invoice object
    
      {
        "data": [
            {
                "object": "refunds",
                "id": "83cd9f6d-481a-49c4-9cc1-954c065e6063",
                "transaction_id": "10e7691c-14a2-4936-833b-ec154c817ce9",
                "amount": {
                        "amount": "6000",
                        "currency": "MAD"
                },
                "currency": "MAD",
                "amount_in_mad": {
                    "amount": "6000",
                    "currency": "MAD"
                },
                "status": 1,
                "status_text": "succeeded",
                "reason": 1,
                "reason_text": "duplicate",
                "created_at": 1706534112,
                "transaction": {
                    "data": {
                        "object": "transaction",
                        "id": "10e7691c-14a2-4936-833b-ec154c817ce9",
                        "created_at": 1706515890,
                        "paid_at": 1706515899,
                        "status": 1,
                        "status_text": "paid",
                        "customer": "38678dea-d23a-4388-bb78-648892bce85b",
                        "order_id": "inv_028ef20c-5065-4515-a0d6-a1c17ff0d53e",
                        "payment_method": {
                            "type": "credit_card",
                            "id": "0fd9bb2c-f14b-411c-bc90-deb73ddaf9ff"
                        },
                        "amount": {
                            "amount": "10000",
                            "currency": "MAD",
                            "localized": "MAD 100.00"
                        },
                        "fees": {
                            "amount": "690",
                            "currency": "MAD",
                            "localized": "MAD 6.90"
                        },
                        "metadata": {
                            "type": "youcan_pay.invoice"
                        },
                        "customer_ip": "192.168.65.1"
                    }
                }
            },
            {...},
        ],

        "meta": {
            "pagination": {
                "total": 6,
                "count": 6,
                "per_page": 10,
                "current_page": 1,
                "total_pages": 1,
                "links": {}
            }
        }
    }
    
  

Currencies

Conversion rates

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

The conversion rates object


base_currency string

The base currency for conversion rates.


conversion_rates object

An object containing currency conversion rates.


conversion_rates.EUR float

Conversion rate from base currency to Euro (EUR).


conversion_rates.GBP float

Conversion rate from base currency to British Pound (GBP).


conversion_rates.MAD float

Conversion rate from base currency to Moroccan Dirham (MAD).


conversion_rates.? float

Conversion rate from base currency to ...

get /currency/conversion-rates
    
      $ curl --location -g --request GET 'https://api.youcanpay.com/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,
    ...
  }
}
    
  

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.


description string

A brief description of the invoice.


active boolean

Indicates whether the invoice is active.


status integer

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


status_text string

Textual representation of the invoice status.


created_at integer

Timestamp of when the invoice was created.


due_by integer

Timestamp of when the invoice is due, if applicable.


deleted_at integer

Timestamp of when the invoice was deleted, if applicable.


link string

URL link to the invoice.


amount.amount string

The total amount of the invoice.


amount.currency string

The currency of the invoice amount.


amount.localized string

The localized representation of the invoice amount.

get /invoices/inv_028ef20c-5065-4515-a0d6-a1c17ff0d53e
    
      $ curl --location -g --request GET 'https://api.youcanpay.com/invoices/inv_028ef20c-5065-4515-a0d6-a1c17ff0d53e
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
The invoice object
    
      {
    "data": {
      "object": "invoice",
      "id": "inv_028ef20c-5065-4515-a0d6-a1c17ff0d53e",
      "reference": "0000000016",
      "name": "eee",
      "description": "test test.",
      "active": true,
      "status": 0,
      "status_text": "pending",
      "created_at": 1706459720,
      "due_by": null,
      "deleted_at": null,
      "link": "https://youcanpay.com/i/TwRLnwU",
      "amount": {
        "amount": "10000",
        "currency": "MAD",
        "localized": "MAD 100.00"
      }
    }
  }
    
  

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 is represented in a small integer format. For example, an amount of 10000 equal 100 DH


currency required

The currency linked to your amount in capital letters.


description required

A description that does not exceed 500 characters.


active optional

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

Returns


Returns an invoice object if the request was successful.

post /invoices
    
      $ curl --location --request POST 'https://api.youcanpay.com/invoices' \
  --form 'name="samir"' \
  --form 'amount="10000"' \
  --form 'currency="MAD"' \
  --form 'description="Hello this is me saying hello"' \
  --form 'to="+212669336603"' \
  --form 'active="1"' \
  --form 'reference="tes ref"' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
The response object
    
      {
        "data": {
            "object": "invoice",
            "id": "inv_22959e71-8b90-455d-9f4c-d32b5699950c",
            "reference": "0000000020",
            "name": "Invoice test",
            "description": "test test test test test",
            "active": false,
            "status": 0,
            "status_text": "pending",
            "created_at": 1706535358,
            "due_by": null,
            "deleted_at": null,
            "link": "https://youcanpay.com/i/6P1OEzW",
            "amount": {
                "amount": "1200",
                "currency": "MAD",
                "localized": "MAD 12.00"
            },
            "transactions": {
                "data": []
            }
        }
    }
    
  

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://api.youcanpay.com/invoices
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
get /invoices
    
      $ curl --location -g --request GET 'https://api.youcanpay.com/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": {...}
  }
    
  

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.

get /withdrawals/756e502e-d363-42f1-85f0-0b6b43f4d486
    
      $ curl --location -g --request GET 'https://api.youcanpay.com/withdrawals/756e502e-d363-42f1-85f0-0b6b43f4d486
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
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://api.youcanpay.com/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://api.youcanpay.com/withdrawals
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'
    
  
get /withdrawals
    
      $ curl --location -g --request GET 'https://api.youcanpay.com/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": {...}
  }