Deposit Creation Endpoint

Deposit creation

POST https://api-stg.tupayonline.com/v3/deposits

This endpoint allows you to generate deposit transactions.

Headers

Name	Type	Description
Content-Type	string	application/json
X-Date	string	ISO8601 Datetime with Timezone: yyyy-MM-dd'T'HH:mm:ssZ
X-Login	string	Merchant X-Login API Key
Authorization	string	Authorization control hash
X-Idempotency-Key	string	Unique idempotency key

Request Body

Name	Type	Description
country*	string	Country of the deposit
amount*	number	Amount of the deposit
invoice_id*	string	Unique deposit ID on your side
currency*	string	Currency of the deposit
request_payer_data_on_validation_failure	boolean	Flag specifying if you want to ignore errors because of invalid phone, zip_code and/or city's state
payer*	object	Object containing details about the customer. See "Payer object" section for details
client_ip	string	Valid IPv4/v6 Address of the customer
device_id	string	Unique customer's device ID created using our JS library
back_url*	string	HTTPS URL used to redirect the customer in case of cancelling the deposit
success_url*	string	HTTPS URL used to redirect the customer in case of success
error_url*	string	HTTPS URL used to redirect the customer in case of error while generating the payment
notification_url*	string	HTTPS URL used to send the notifications about deposit's change of status
logo	string	HTTPS URL used as the Merchant logo on our cashier
test	boolean	Used to mark a deposit as test. If true, the deposit will not affect the merchant's balance
mobile	boolean	Used to specify if the redirection will be made on a mobile device
payment_method*	string	Must be sent with value XA

201 Deposit request created successfully with ONE_SHOT Experience

{
    "checkout_type": "ONE_SHOT",
    "redirect_url": "https://checkout-stg.directa24.com/v1/gateway/show?id_payment=56578849&signature=fff0e0a6a98066c19caf",
    "deposit_id": 300000025,
    "user_id": "11",
    "merchant_invoice_id": "postmanTest943044826",
    "payment_info": {
        "type": "BANK_DEPOSIT",
        "payment_method": "BB",
        "payment_method_name": "Banco do Brasil",
        "amount": 49.99,
        "currency": "BRL",
        "expiration_date": "2020-06-17 07:04:16",
        "created_at": "2020-06-16 19:04:16",
        "metadata": {
            "beneficiary_name": "Directa24 LLP",
            "agency": "3229-X",
            "CNPJ": "33.444.368/0001-39",
            "account": "253393-4"
        }
    }

400 Deposit request failed due to field validation error

{
    "code": 201,
    "description": "Field validation error. Check details",
    "details": [
        "invoiceId: must match \"^[A-Za-z0-9]*$\""
    ]
}

Flows

ONE_SHOT	HOSTED
The deposit request was successfully completed in One Shot and the user will be directly presented with the information to complete the payment.	The information sent is missing details required to complete the request. Redirect the customer to our Hosted Checkout to collect those details.
Below you will find all the Required fields with a checkbox	If required fields are missing, the HOSTED flow will take place 👍

Example Request

{
	"country":"PE",
	"currency":"PEN",
	"amount":50,
	"payment_method":"XA",
	"payer":
	{
		"document_type":"CE",
		"document":"526263538",
		"first_name":"Martin",
		"last_name":"Martins",
		"email":"[e-mail]"
	},
	"notification_url":"https://notification-url.com/",
	"back_url":"https://back-url.com/",
	"success_url":"https://success-url.com/",
	"error_url":"https://error-url.com/"
}

Request fields

Required	Field name	Format	Description	Default	Validations
	country	string (length: 2)	Country code of the deposit in ISO 3166-1 alpha-2 code format	​	​Country codes​
	amount	decimal (max decimals: 2)	Deposit amount in the currency specified	​	Number of up to 18 integers and 2 decimals places
	currency	string (length: 3)	Currency code of the amount in ISO 4217 format	USD	​Currencies​
	invoice_id	string (max length: 128)	Unique deposit ID on the merchant end	random	^[A-Za-z0-9-_]*$
	payer	object[]	Object containing details about the customer	​	​Payer object​
	payment_method	string (length: 2)	Must be sent with value XA XAQR	XA XAQR	Payment Methods
	success_url	string (max length: 2048)	Valid URL over HTTPS used to redirect the customer in case the deposit flow was completed.	​	HTTPS URL
	back_url	string (max length: 2048)	Valid URL over HTTPS used to redirect the customer.	​	HTTPS URL
	error_url	string (max length: 2048)	Valid URL over HTTPS used to redirect the customer in case of error while generating the deposit	​	HTTPS URL
	notification_url	string (max length: 2048)	Valid URL over HTTPS used to receive the notifications about the deposit's changes of status. If none is sent, we will use the one configured on the Tupay Panel	​	HTTPS URL
	fee_on_payer	boolean	Choose if the deposit's fee will be paid by the customer or debited from your balance	false	[true, false]
	client_ip	string	Valid IPv4 or IPv6 Address	​	IPv4/v6 Address
	device_id	string (max length: 100)	Unique customer's device ID. Used to identify and prevent fraud.	​	String of up to 100 characters
	test	boolean	Used to flag a deposit as test. If true, the deposit will not affect the merchant's balance	false	[true, false]
	mobile	boolean	Used to specify if the redirection will be made on a mobile device	false	[true, false]
	request_payer_data_on _validation_failure	boolean	Boolean used to specify if you want to receive declines by invalid data even if it is not required by the payment method. here for more info	false	[true, false]

Payer Object

Required	Field name	Format	Description	Default	Validations
	id	string (max length: 128)	Customer's ID generated on your end. Used to locate user's transaction on our Tupay Panel	If none is sent, we will autogenerate it	^[A-Za-z0-9]*$
	document	string (max length: 30)	Customer's document ID. Ensure it is correct and the user can't change it every time he/she deposits	​	​document validations​
	document_type	string (max length: 10)	Customer's document type. Optional, if sent must be a valid document type	​	​document types validations​
	email	string (max length: 255)	Valid customer's email address	​	Valid email address
	first_name	string (max length: 128)	Customer's first name	​	String of up to 128 characters
	last_name	string (max length: 128)	Customer's last_name	​	String of up to 128 characters
	phone	string (max length: 32)	Valid customer's phone number	​	​phone number validations​
	address	object	Object containing customer's address details	​	​address object​

Payer.address Object

Required	Field name	Format	Description	Validations
	street	string (max length: 255)	Customer's street	String of up to 255 characters
	city	string (max length: 128)	Customer's city	String of up to 128 characters
	state	string (max length: 3)	Customer's state code in ISO 3166-2 code format	Valid state code in ISO 3166-2 format. Check our States endpoint here
	zip_code	string (max length: 16)	Customer's zip code	zip_code validations

Flags

We recommend sending the following flags to prevent declines and improve conversion rates.

mobile

The flag mobile is a boolean and has to be sent equal to true if the customer generating the deposit is using a mobile device/application. If not sent it defaults to false.

There are some payment methods that have a different flow on mobile devices compared to the flow on web devices because the payment method doesn't work the same way in those devices. When a deposit gets created as ONE_SHOT, it means the flow is assigned before the user navigates into our website, and therefore, we can't identify if the customer comes from a mobile device or not.

Considering that, if the flag mobile is not sent we could route a mobile user through the web flow, therefore, affecting the ability of the customer to complete the deposit.

request_payer_data_on_validation_failure

The flag request_payer_data_on_validation_failure can be used to prevent the request to be declined in case you send an invalid payer.phone, payer.address.state and/or payer.address.zip_code.