> ## Documentation Index
> Fetch the complete documentation index at: https://developer.paymee.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a loan
> Creates a loan based on a previously approved proposal
## OpenAPI
````yaml post /v1.1/loans/create
openapi: 3.0.3
info:
title: API PayMee 1.1
description: >-
# Overview
The purpose of this documentation is to guide the developer on how to
integrate with PayMee, describing the features and methods to be used,
listing information to be sent and received as well as providing examples.
The integration mechanism with PayMee is simple, so only intermediate
knowledge in Web programming language, HTTP/HTTPS requests and JSON file
manipulation are required to successfully deploy the PayMee solution.
In this manual you will find reference to all operations available on the
API REST of the PayMee API. These operations must be performed using
specific keys (**x-api-key** and **x-api-token**) on the respective
environment endpoints:
Production Environment
[https://api.paymee.com.br/](https://api.paymee.com.br/)
Sandbox Environment
[https://apisandbox.paymee.com.br/](https://apisandbox.paymee.com.br/)
To perform an operation, combine the base URL of the environment with the
resource (URI) of the desired operation and send it using the HTTP verb as
described in the operation.
# Solution features
The API solution of the PayMee platform was developed with REST technology,
which is the market standard and also independent from the technology used
by other parties. This way, it is possible to integrate it through the great
majority of programming languages, such as: ASP, ASP. Net, Java, PHP, Ruby,
Python, etc.
Amongst other features, the attributes that stand out the most in the PayMee
platform are:
**No proprietary apps**: it is not necessary to install any applications in
the virtual shop environment, under no circumstances.
**Simplicity**: the protocol used is purely HTTPS.
**Ease of testing**: the PayMee platform offers a publicly accessible
Sandbox environment, which allows the developer to create a [test
account](https://sandbox.paymee.com.br/register) making it easier and faster
to start integration.
**Credentials**: handling of the customer’s credentials (**x-api-key** and
**x-api-token**) traffics in the header of the HTTP request of the message.
**Safety**: the information exchange always takes place between the store's
Server and PayMee's Server, that is, without the buyer’s browser in between.
**Multiplatform**: the integration is performed through the REST Web
Service.
# Architecture
Integration is performed through Web Services. The model employed is quite
simple: There are two URLs (endpoints) available: a specific one for
production (real time operation), and a specific one for testing, called
sandbox.
These URLs receive the HTTP messages through the **POST**, **GET** or
**PUT** methods. Each message type must be sent to a resource identified
through the path.
| **METHOD** | **DESCRIPTION** |
| --- | --- |
| POST | The **POST** HTTP method is used in the creation of resources or
sending information that will be processed. For example, creation of a
transaction. |
| PUT | The **PUT** HTTP method is used to update an already existing
resource. For example, refunding or cancelation of a previous transaction. |
| GET | The **GET** HTTP method is used for querying already existing
resources. For example, transaction query. |
## Supported Payment Methdos
The current version of PayMee Webservice supports the following payment
methods:
| BANK | WIRE TRANSFER | CASH | CREDIT CARD |
| --- | --- | --- | --- |
| 001 - BANCO DO BRASIL | YES | YES | NO |
| 237 - BANCO BRADESCO | YES | NO | NO |
| 104 - BANCO CAIXA ECONOMICA FEDERAL | YES | NO | NO |
| 341 - BANCO ITAÚ-UNIBANCO | YES | YES | NO |
| 033 - BANCO SANTANDER BRASIL | YES | YES | NO |
| 212 - BANCO ORIGINAL | YES | NO | NO |
| 077 - BANCO INTER | YES | NO | NO |
| 218 - BANCO BS2 | YES | NO | NO |
| PIX | YES | NO | NO |
| CREDIT CARD | NO | NO | YES |
# Sandbox and Tools
## About Sandbox
To facilitate testing during integration, PayMee offers a Sandbox
environment, which is composed by two areas:
- Test account register
- Transactional Endpoint
- Request: [https://apisandbox.paymee.com.br](https://apisandbox.paymee.com.br)
Advantages of using the Sandbox
No affiliation is required to use PayMee's Sandbox. You just have to access
the Sandbox Registration, create an account and, with it, receive a
**x-api-key** and a **x-api-token**, which are the credentials required for
the API methods.
You can create your sandbox account here:
[https://sandbox.paymee.com.br/register](https://sandbox.paymee.com.br/register)
# Webhook
## Notification Post
The Notification Post is sent based on a selection of events to be made in
the PayMee registry.
The events that can be notified are:
| EVENT TYPE | EVENT |
| --- | --- |
| SALE | PAID |
| REVERSAL | CREATE/PAID |
PayMee's send the notifications to the URL that you have configured using
the HTTP protocol, by the POST method.
**Authentication**
Basic http auth.
The username is your **x-api-key** and password is your **x-api-token**
**Base64 Basic Auth reference:**
**x-api-key** = af38b751-30d7-4261-a9fb-ea30f6ece609
**x-api-token** = 28331f43-e2b3-4078-9502-5f656fb66cdf
### TRANSFER/WALK-IN NOTIFICATION (PAYMENT CONFIRMATION)
Here is an example of a notification sent by PayMee (the lines have been
broken for ease of reading):
```
POST /callback HTTP/1.1
Authorization: Basic
YWYzOGI3NTEtMzBkNy00MjYxLWE5ZmItZWEzMGY2ZWNlNjA5OjI4MzMxZjQzLWUyYjMtNDA3OC05NTAyLTVmNjU2ZmI2NmNkZg==
Content-Length:272
Content-Type:application/json
{
"saleToken": "d59b39ce-bffd-3f6d-80c4-c376a242afd1",
"referenceCode":"0000000000014",
"currency": "BRL",
"amount":100.00,
"shopper":{
"id": "12911",
"firstName":"Teste",
"lastName":"Silva",
"email":"teste@teste.com.br",
"agency": "1234",
"account": "123456-0"
},
"date":"2017-07-28 10:48:56",
"newStatus": "PAID"
}
```
A Payment Status URL must be registered, so that the notification POST is
executed.
The callback URL should return the HTTP status 200. Otherwise PayMee will
try again in 60-seconds interval for a maximum of 5 (five) attempts.
## Response
| **PROPERTY** | **TYPE** | **DESCRIPTION** |
| --- | --- | --- |
| saleToken | string | transaction UUID |
| referenceCode | string | order identification |
| amount | number | order amount |
| shopper.firstName | string | shopper's first name |
| shopper.firstName | string | shopper's last name |
| shopper.email | string | shopper's email |
| shopper.agency | string | shopper's agency |
| shopper.account | string | shopper's account |
| date | string | payment date and time (yyyy-MM-dd HH:mm:ss) |
| newStatus | string | payment PAID status |
### REVERSAL NOTIFICATION
Here is an example of a notification sent by PayMee (the lines have been
broken for ease of reading):
```
POST /callback?reversing=true&type=reversing HTTP/1.1
Authorization: Basic
YWYzOGI3NTEtMzBkNy00MjYxLWE5ZmItZWEzMGY2ZWNlNjA5OjI4MzMxZjQzLWUyYjMtNDA3OC05NTAyLTVmNjU2ZmI2NmNkZg==
Content-Length:272
Content-Type:application/json
{
"id": 611212,
"uuid": "d19b39ce-bffd-3f6d-80c4-c376a242afd3",
"currency": "BRL",
"originalAmount":100.00,
"reversedAmount":100.00,
"status": "PENDING",
"bankDetails":{
"bank": "341 - BANCO ITAÚ-UNIBANCO S.A.",
"branch":"0000",
"account":"00000-0"
},
"sale": {
"id": 611210,
"uuid": "75e0b5e2-bc3f-4e75-9c52-24096f2e004d"
}
"creation": "2018-04-15 08:33:22",
"receipt": null,
"reason": "amount greater than total of sale"
}
```
A Reversal Status URL must be registered (just like the payment
notification) and you **must enable** this feature on your [merchant
panel](https://www2.paymee.com.br/merchants/API), so the notification POST
is executed.
This notification occurs two moments:
- when we cannot approve or identify the sale - In this case, we send the
status attribute as **PENDING**;
- when we revert the amount successfully to the customer - In this case, we
send the status attribute as **PAID**
The callback URL should return the HTTP status 200. Otherwise PayMee will
try again in 60-seconds interval for a maximum of 5 (five) attempts.
## Response
| **PROPERTY** | **TYPE** | **DESCRIPTION** |
| --- | --- | --- |
| id | number | transaction id |
| uuid | string | transaction uuid |
| currency | string | order currency |
| originalAmount | number | original order amount |
| reversedAmount | number | reversed amount |
| bankDetails.bank | string | credit bank |
| bankDetails.branch | string | credit branch |
| bankDetails.account | string | credit account |
| receipt | string | reversal receipt (under development) |
| status | string | reversal status (PENDING/PAID/CANCELLED) |
| reason | string | reversal reason |
| date | string | reversal date (yyyy-MM-dd HH:mm:ss) |
### REFUND NOTIFICATION
Here is an example of a notification sent by PayMee (the lines have been
broken for easy reading):
```
POST /callback?refund=true&type=refund HTTP/1.1
Authorization: Basic
YWYzOGI3NTEtMzBkNy00MjYxLWE5ZmItZWEzMGY2ZWNlNjA5OjI4MzMxZjQzLWUyYjMtNDA3OC05NTAyLTVmNjU2ZmI2NmNkZg==
Content-Length:272
Content-Type:application/json
{
"saleToken": "d19b39ce-bffd-3f6d-80c4-c376a242afd3",
"referenceCode":"0000000000014",
"currency": "BRL",
"originalAmount":150.00,
"reversedAmount":50.00,
"bankDetails":{
"bank": "341 - BANCO ITAÚ-UNIBANCO S.A.",
"branch":"0000",
"account":"00000-0"
},
"receipt": "null",
"status": "PAID",
"refund": {
"id": 611211,
"uuid": fbebcd28-ae51-11e9-a2a3-2a2ae2dbcce4,
"status": "PAID",
"amount": 50.00,
"creation": "2018-04-15 08:33:22",
"creditDate": "2018-04-16 10:48:56"
}
"reason": "amount greater than total of sale",
"date":"2018-04-16 10:48:56"
}
```
A Refund Status URL must be registered (The same as the payment
notification) and you **must enable** this feature on your **merchant
panel**, so the notification POST is executed.
This notification occurs when:
- Refund the amount successfully - In this case, we send the status
attribute as **PAID**
The callback URL should return the HTTP status 200. Otherwise PayMee will
try again in 60-seconds interval for a maximum of 5 (five) attempts.
## Response
| **PROPERTY** | **TYPE** | **DESCRIPTION** |
| --- | --- | --- |
| saleToken | string | transaction UUID |
| referenceCode | string | order identification |
| currency | string | order currency |
| originalAmount | number | original order amount |
| amountRefunded | number | refund amount |
| bankDetails.bank | string | credit bank |
| bankDetails.branch | string | credit branch |
| bankDetails.account | string | credit account |
| receipt | string | refund receipt (under development) |
| status | string | refund status (PENDING/PAID/CANCELLED) |
| reason | string | refund reason |
| date | string | refund date (yyyy-MM-dd HH:mm:ss) |
### PAYOUT NOTIFICATION
Here is a success example of a notification sent by PayMee (the lines have
been broken for ease of reading):
```
POST /callback?type=payout HTTP/1.1
Authorization: Basic
YWYzOGI3NTEtMzBkNy00MjYxLWE5ZmItZWEzMGY2ZWNlNjA5OjI4MzMxZjQzLWUyYjMtNDA3OC05NTAyLTVmNjU2ZmI2NmNkZg==
Content-Length:272
Content-Type:application/json
{
"success": true,
"message": "success"
"id": 611212,
"uuid": "d19b39ce-bffd-3f6d-80c4-c376a242afd3",
"currency": "BRL",
"amount":100.00,
"status": "PAID",
"referenceCode": "XPADOA",
"bankDetails":{
"bank": "341 - BANCO ITAÚ-UNIBANCO S.A.",
"branch":"0000",
"account":"00000-0"
},
"creation": "2018-04-15 08:33:22",
"receipt": "https://receipts.paymee.com.br/transaction/23e49aa1f7f193395a7f30900f8aeb40a65a9d7dd85e8d05456847b800713546/d19b39ce-bffd-3f6d-80c4-c376a242afd3",
}
```
Here is a error example of a notification sent by PayMee (the lines have
been broken for ease of reading):
```
POST /callback?payout=true HTTP/1.1
Authorization: Basic
YWYzOGI3NTEtMzBkNy00MjYxLWE5ZmItZWEzMGY2ZWNlNjA5OjI4MzMxZjQzLWUyYjMtNDA3OC05NTAyLTVmNjU2ZmI2NmNkZg==
Content-Length:272
Content-Type:application/json
{
"success": false,
"message": "Os dados informados não são validos",
"error_code": "PE0001"
"id": 611212,
"uuid": "d19b39ce-bffd-3f6d-80c4-c376a242afd3",
"currency": "BRL",
"amount":100.00,
"status": "PENDING",
"referenceCode": "XPADOA",
"bankDetails":{
"bank": "341 - BANCO ITAÚ-UNIBANCO S.A.",
"branch":"0000",
"account":"00000-0"
},
"creation": "2018-04-15 08:33:22",
"receipt": "https://receipts.paymee.com.br/transaction/23e49aa1f7f193395a7f30900f8aeb40a65a9d7dd85e8d05456847b800713546/d19b39ce-bffd-3f6d-80c4-c376a242afd3",
}
```
A webhook URL must be registered (just like the payment notification) and
you **must enable** this feature on your [merchant
panel](https://www2.paymee.com.br/merchants/API), so the notification POST
is executed.
## Response
| **PROPERTY** | **TYPE** | **DESCRIPTION** |
| --- | --- | --- |
| success | boolean | payments status flag |
| message | string | return message |
| error_code | string | response error code |
| id | number | PayMee's transaction id |
| uuid | string | PayMee's transaction uuid |
| currency | string | transaction currency |
| amount | number | transaction amount |
| status | string | refund status (PENDING/PAID/CANCELLED) |
| bankDetails.bank | string | credit bank |
| bankDetails.branch | string | credit branch |
| bankDetails.account | string | credit account |
| receipt | string | payment receipt |
| date | string | transaction date (yyyy-MM-dd HH:mm:ss) |
| receiptDate | string | receipt date (yyyy-MM-dd HH:mm:ss) |
## Error codes
| **PROPERTY** | **DESCRIPTION** |
| --- | --- |
| PE0001 | Os dados bancarios fornecidos não validos |
| PE0002 | A titularidade da conta não pertence ao documento informado |
| PE0003 | A conta nao aceita movimentacoes - (MOTIVOS) |
| PE0004 | OUTROS - (MOTIVOS) |
# Resources
version: 1.0.0
contact: {}
servers:
- url: https://api.paymee.com.br
- url: https://apisandbox.paymee.com.br
security: []
tags:
- name: Checkouts
description: '**Our API collections for checkout requests**'
- name: loans
- name: Payouts
description: '**Our API collection for Payouts requests**'
paths:
/v1.1/loans/create:
post:
tags:
- Checkouts
- loans
summary: Create a loan
description: Creates a loan based on a previously approved proposal
operationId: create
parameters:
- name: x-api-key
in: header
required: true
schema:
type: string
example: your-api-key-here
description: API authentication key
- name: x-api-token
in: header
required: true
schema:
type: string
example: your-api-token-here
description: API authentication token
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- proposal_id
- reference_code
- customer
- final_amount
- max_age
- discriminator
properties:
proposal_id:
type: string
description: Proposal ID from a previous loan simulation
example: abc1234
reference_code:
type: string
description: Merchant reference code for tracking
example: ref01234
max_age:
type: integer
description: Validity period in minutes
example: 60
discriminator:
type: string
description: Optional field for categorization
example: John's transaction
final_amount:
type: number
description: Final amount to be paid
example: 10
customer:
type: object
required:
- name
- birth
- email
- mobile_number
- document
- address
properties:
name:
type: string
description: Customer's full name
example: John Doe
birth:
type: string
format: date
description: Customer's birth date in YYYY-MM-DD format
example: '1970-01-01'
email:
type: string
format: email
description: Customer email address
example: foo@bar.com
mobile_number:
type: string
description: Customer mobile phone number
example: '11999999999'
document:
type: object
required:
- type
- number
properties:
type:
type: string
enum:
- CPF
- CNPJ
description: >-
Document type (CPF for individuals, CNPJ for
companies)
example: CPF
number:
type: string
description: Document number
example: '00000000000'
address:
type: object
required:
- zipcode
- street
- number
- city
- state
properties:
zipcode:
type: string
description: Postal code
example: '12345678'
street:
type: string
description: Street name
example: Main Street
number:
type: string
description: Building number
example: '123'
complement:
type: string
description: Additional address information
example: Apt 4
neighborhood:
type: string
description: Neighborhood name
example: Downtown
city:
type: string
description: City name
example: City
state:
type: string
description: State/province code
example: ST
examples:
StandardLoan:
summary: Standard loan creation request
value:
proposal_id: abc1234
reference_code: ref01234
max_age: 60
discriminator: John's transaction
final_amount: 10
customer:
name: John Doe
birth: '1970-01-01'
email: foo@bar.com
mobile_number: '11999999999'
document:
type: CPF
number: '00000000000'
address:
zipcode: '12345678'
street: Main Street
number: '123'
complement: Apt 4
neighborhood: Downtown
city: City
state: ST
responses:
'200':
description: Loan creation response
content:
application/json:
schema:
oneOf:
- type: object
properties:
amount:
type: number
description: Principal loan amount
example: 800
appliedRate:
type: number
description: Applied rate
example: 0
chosen_term:
type: object
description: Selected payment term details
creation:
type: string
description: Loan creation date and time
currency:
type: string
description: Currency code
discounts:
type: number
description: Applied discounts
id:
type: number
description: Internal loan ID
maxAge:
type: string
description: Loan expiration date and time
message:
type: string
description: Response message
example: success
referenceCode:
type: string
description: Merchant reference code
shipping:
type: number
description: Shipping costs if applicable
shopper:
type: object
description: Customer information
situation:
type: string
description: Loan status
example: PENDING
status:
type: number
description: Response status code
example: 0
total:
type: number
description: Total loan amount
type:
type: string
description: Transaction type
example: SALE
uuid:
type: string
description: Unique loan identifier
- type: object
properties:
status:
type: number
description: Response status code
example: -1
message:
type: string
description: Response message
example: proposal not accept
proposalAccepted:
type: boolean
description: Indicates if the proposal was accepted
example: false
examples:
Success response:
summary: Standard loan creation success
value:
amount: 800
appliedRate: 0
chosen_term:
amount: 800
final_amount: 845.31
interest_rate: 7.17
label: 03x
monthly_interest_rate: 2.39
quotas: 281.77
times: 3
creation: '2021-03-17 10:43:49'
currency: BRL
discounts: 0
id: 43863
maxAge: '2021-03-19 02:40:49'
message: success
referenceCode: 5077AXC
shipping: 0
shopper:
bankDetails: {}
document:
number: '00000000000'
type: CPF
email: foo@bar.com
name: JOHN DOE
phone:
number: '+5511999999999'
type: MOBILE
situation: PENDING
status: 0
total: 800
type: SALE
uuid: d7113995-e683-35b6-bf4f-7846ebc63819
Proposal not accepted:
summary: Proposal not accepted
value:
status: -1
message: proposal not accepted
proposalAccepted: false
'400':
description: Validation errors
content:
application/json:
schema:
type: object
properties:
errorCount:
type: number
description: Number of validation errors
example: 1
errors:
type: array
description: List of validation errors
items:
type: object
properties:
field:
type: string
description: Field with error
example: terms
message:
type: string
description: Error message
example: must be between 1 and 12
main_error_message:
type: string
description: Primary error message
example: must be between 1 and 12
message:
type: string
description: General error message
example: validation failure
status:
type: number
description: Error status code
example: -1
examples:
Invalid terms response:
summary: Invalid terms value
value:
status: -1
message: validation failure
errorCount: 1
errors:
- field: terms
message: must be between 1 and 12
main_error_message: must be between 1 and 12
Invalid proposal ID response:
summary: Invalid proposal ID
value:
status: -1
message: validation failure
errorCount: 1
errors:
- field: invalid proposal id
message: invalid proposal id
'403':
description: Unauthorized access
content:
application/json:
schema:
type: object
properties:
errorCount:
type: number
example: 1
errors:
type: array
items:
type: object
properties:
error:
type: string
example: Forbidden
message:
type: string
example: Access Denied
example:
- error: Forbidden
message: Access Denied
message:
type: string
example: field validation failure
status:
type: number
example: -1
examples:
Unauthorized access:
summary: Unauthorized access
value:
errorCount: 1
errors:
- error: Forbidden
message: Access Denied
message: field validation failure
status: -1
````