2. Criando uma Cobrança

Este recurso permite que seja criada uma solicitação de pagamento. O cliente/pagador precisará acessar a página de pagamento para finalizar o processo.

Caso já exista uma cobrança com o mesmo código, e ela ainda estiver em uma situação que permite pagamento, o valor da cobrança será atualizado com o valor enviado.

Se você está procurando o recurso para gerar um pagamento sem que o cliente precise acessar uma página para realizar o processo, consulte a API Direct.

Endpoint URL

POST https://api.southpayments.com/checkout/orders

AUTENTICAÇÃO

Veja a seção "Autenticação e Autorização".

REQUEST BODY (Json)

Nome	Tipo	Obrigatório	Tamanho Máximo / Valores	Comentário/Exemplo
merchant_id	string	sim	15	Código de estabelecimento fornecido pela Southpayments. Ex: 987heuiwqg8912g
order	object	sim	-	Objeto com os parâmetros da cobrança, descritos abaixo.
order.amount	integer	sim	10	Valor total da cobrança, em centavos, somente números, sem pontos nem vírgulas. Ex: 5000 (significa R$50,00)
order.merchant_key	string	sim	40	Código único que identifica a cobrança.
order.description	string	não	255	Descrição da cobrança. Aparece para o cliente na tela de pagamento.
order.sandbox	boolean	não	true/false	Indica se é uma cobrança de teste ou não. Padrão FALSO.
order.notify_customer	string	não	email sms both none	Indica se deve notificar o cliente por email e/ou SMS*. Se não informado, respeitará a configuração do Painel de Controle.
order.notify_url	string	não	URL	URL de seu sistema para a qual será enviado um POST  sempre que houver atualização de status. Será enviado um JSON com um Objeto Cobrança.
order.payment_failure_url	string	não	URL	URL de seu sistema para a qual será enviado um POST  quando houver uma tentativa de pagamento com falha. Será enviado um JSON com um Objeto Pagamento.
order.customer	object	não***	-	Dados do cliente, atributos descritos abaixo.
customer.customer_type	integer	sim**	1	0 - Pessoa Física 1 - Pessoa Jurídica
customer.merchant_key	string	não***	40	Código identificador de seu cliente
customer.name	string	não***	255	Nome do cliente
customer.email	string	não	255	E-mail do cliente. Obrigatório para envio de notificações ao cliente por e-mail.
customer.phone_country_code	string	não	2	Código de área do telefone do cliente. Se não for enviado, considera 55 (Brasil) Ex: 55
customer.phone_number	string	não	15	Telefone do cliente com DDD. Apenas números. Necessário ser telefone celular para envio de SMS. Ex: 11987654321
customer.legal_number	string	não***	20	CPF (pessoa física) ou CNPJ (pessoa jurídica). Apenas números. Ex: 33333333333
customer.billing_zipcode	string	não***	10	Código postal do endereço do cliente. Ex: 01234567
customer.billing_street	string	não***	100	Logradouro do cliente. Ex: Rua da Luz
customer.billing_number	string	não***	10	Número do endereço. Ex: 1234
customer.billing_additional	string	não	30	Complemento do endereço (apto, casa, etc). Ex: Casa 3
customer.billing_district	string	não	60	Bairro do endereço. Ex: Centro
customer.billing_city	string	não***	60	Cidade do endereço. Ex: São Paulo
customer.billing_state	string	não***	2	UF do endereço. Ex: SP
order.payments_settings	array	não		Array indicando os meios de pagamentos disponibilizados para esta cobrança. Se não for enviado, considera os meios habilitados no painel de controle.
payments_settings.payment_type	string	sim**	boleto credit_card pix	Indica o meio de pagamento
payments_settings.discount	float	não	0..100	Percentual de desconto aplicado ao valor da cobrança caso este meio de pagamento seja escolhido. Ex: 15
payments_settings.addition	float	não	0..100	Percentual de acréscimo aplicado ao valor da cobrança caso este meio de pagamento seja escolhido. Ex: 5.25
payments_settings.boleto_due_days	integer	não****	0..999	Apenas para BOLETO, prazo de vencimento do boleto em dias, a partir da data de emissão. Ex: 3
payments_settings.boleto_due_date	string	não****	yyyy-mm-dd	String no formato "yyyy-mm-dd" indicando a data de vencimento do boleto. Ex: 2020-10-29
payments_settings.max_installments	integer	não	1..12	Apenas para CREDIT CARD, indica o máximo de parcelas possíveis SEM JUROS para esta cobrança, até 12. Se não for enviado, considera o configurado no painel de controle. Ex: 10
payments_settings.boleto_void_days	integer	não	1..60	Apenas para BOLETO, indica o prazo para cancelamento do boleto no banco, impedindo o pagamento. Se não for enviado, considera o configurado no painel de controle. Ex: 30
payments_settungs.boleto_charge_interest	boolean	não	true false	Apenas para BOLETO, indice se deve ser cobrado juros para pagamento após o vencimento. Se não for enviado, considera o configurado no painel de controle. Ex: true
payments_settings.boleto_interest_type	string	não*****	fixed percentage	Apenas para BOLETO, indica se o juros cobrado serão um percentual ao mês ou um valor fixo em R$ ao dia. Ex: fixed
payments_settings.boleto_interest_amount	float	não*****	0.01..n	Apenas para BOLETO, indica o valor do juros (percentual ou fixo, de acordo com o parâmetro anterior). Ex: 1.99
payments_settungs.boleto_charge_fine	boolean	não	true false	Apenas para BOLETO, indice se deve ser cobrado multa para pagamento após o vencimento. Se não for enviado, considera o configurado no painel de controle. Ex: true
payments_settings.boleto_fine_type	string	não******	fixed percentage	Apenas para BOLETO, indica se a multa cobrada será um percentual do valor do boleto ou um valor fixo em R$. Ex: percentage
payments_settings.boleto_fine_amount	float	não******	0.01..n	Apenas para BOLETO, indica o valor da multa (percentual ou fixo, de acordo com o parâmetro anterior). Ex: 10.50
payments_settings. max_installments_interest	integer	não	1..12	Apenas para CREDIT CARD, indica o máximo de parcelas possíveis COM JUROS para esta cobrança, até 12. Deve ser maior que o max_installments enviado ou configurado no painel de controle. Se for menor, será desconsiderado. Ex: 10
payments_settings.interest	float	não	0..100	Apenas para CREDIT CARD, taxa percentual de juros mensal aplicada no parcelamento com juros. Se não for enviado, considera o configurado no painel de controle. Ex: 1.99

* Apenas para clientes que contrataram o serviço de envio SMS.
** Obrigatório se o objeto no qual este atributo está inserido for enviado.
*** Dados do cliente serão obrigatórios se assim estiver configurado no Painel de Controle.
**** Se nenhum for enviado, considera o prazo configurado no Painel de Controle.

***** Obrigatório se payments_settungs.boleto_charge_interest for "true"

****** Obrigatório se payments_settungs.boleto_charge_fine for "true"

Exemplos

1. Cobrança de R$199,90 que poderá ser paga via Boleto Bancário (prazo de vencimento está configurado no Painel de Controle) ou via Cartão de Crédito em até 5x sem juros. O cliente será notificado por e-mail sobre a cobrança. O texto do e-mail é o configurado no Painel de Controle.

{
  "merchant_id": "4398yfnru3f7813",
  "order": {
    "merchant_key": "codigo-pedido", 
    "amount": 19990, 
    "description": "Descrição da cobrança", 
    "sandbox": false, 
    "notify_customer": "email", 
    "payments_settings": [
     {
      "payment_type": "boleto"
     },
     {
      "payment_type": "credit_card", 
      "max_installments": 5
     }
    ],
    "customer": {
     "customer_type": 0,
     "name": "João Silva",
     "email": "[e-mail]",
     "phone_number": "11999998877",
     "legal_number": "33333333333"
    }
  }
}

2. Cobrança de R$500 que só poderá ser paga via Boleto Bancário, com vencimento em 3 dias. Será cobrada uma multa de 10% para pagamento após o vencimento. O cliente não será notificado sobre esta cobrança.

{
  "merchant_id": "4398yfnru3f7813",
  "order": {
    "merchant_key": "codigo-pedido", 
    "amount": 50000, 
    "description": "Descrição da cobrança", 
    "sandbox": false, 
    "notify_customer": "none", 
    "payments_settings": [
     {
      "payment_type": "boleto",
      "boleto_due_days": 3,
      "boleto_charge_fine": true,
      "boleto_fine_type:": "percentage",
      "boleto_fine_amount": 10
     },
    ],
    "customer": {
     "customer_type": 0,
     "name": "João Silva",
     "email": "[e-mail]",
     "phone_number": "11999998877",
     "legal_number": "33333333333"
    }
  }
}

3. Cobrança de R$2.500 que só poderá ser paga via PIX com 10% de desconto, ou via Cartão de Crédito em até 5x sem juros ou até 12x com juros de 1,99% a.m. O cliente será notificado por sms sobre a cobrança. O texto do sms é o configurado no Painel de Controle.

{
  "merchant_id": "4398yfnru3f7813",
  "order": {
    "merchant_key": "codigo-pedido", 
    "amount": 250000, 
    "description": "Descrição da cobrança", 
    "sandbox": false, 
    "notify_customer": "sms", 
    "payments_settings": [
     {
      "payment_type": "pix",
      "discount": 10,
     },
     {  
      "payment_type": "credit_card", 
      "max_installments": 5,
      "max_installments_interest": 12,
      "interest": 1.99
     }    
    ],
    "customer": {
     "customer_type": 0,
     "name": "João Silva",
     "email": "[e-mail]",
     "phone_number": "11999998877",
     "legal_number": "33333333333"
    }
  }
}

RETORNO - SUCESSO

Código HTTP

201 (CREATED): Cobrança criada com sucesso.
200 (OK): Cobrança atualizada com sucesso.

Corpo da Resposta

Estes são os parâmetros que serão devolvidos se a Cobrança for cadastrada com sucesso.
Você deve encaminhar o cliente para a URL devolvida em "checkout_url" para que ele acesse a página de pagamento.

Nome	Tipo	Valores	Comentário/Exemplo
id	string	-	ID único que identifica a cobrança na Southpayments. Tamanho entre 18 e 20 caracteres. Ex: 987heuiwqg8912gfr4
amount	integer	-	Valor total da cobrança, em centavos, somente números, sem pontos nem vírgulas. Ex: 5000 (significa R$50,00)
checkout_url	URL	-	URL da página de pagamento a ser encaminhada ao Cliente/Pagador.
status	string	open	Status da cobrança. Ao criar via API Checkout, sempre retornará OPEN.
merchant_key	string	-	Código único que identifica a cobrança em seu sistema.
description	string	-	Descrição da cobrança. Aparece para o cliente no Checkout.
sandbox	boolean	true/false	Indica se é uma cobrança de teste ou não.
created_at	string	-	String indicando data e hora de criação da cobrança no formato YYYY-mm-dd HH:MM:SS Ex: 2020-10-20 18:54:30
updated_at	string	-	String indicando data e hora da última atualização da cobrança no formato YYYY-mm-dd HH:MM:SS Ex: 2020-10-20 18:54:30
customer	object	-	Dados do cliente, atributos descritos abaixo.
customer.customer_type	integer	0 / 1	0 - Pessoa Física 1 - Pessoa Jurídica
customer.merchant_key	string	-	Código identificador de seu cliente
customer.name	string	-	Nome do cliente
customer.email	string	-	E-mail do cliente.
customer.phone_country_code	string	-	Código de área do telefone do cliente. Ex: 55
customer.phone_number	string	-	Telefone do cliente com DDD. Apenas números. Ex: 11987654321
customer.legal_number	string	-	CPF (pessoa física) ou CNPJ (pessoa jurídica). Apenas números. Ex: 33333333333
customer.billing_zipcode	string	-	Código postal do endereço do cliente. Ex: 01234567
customer.billing_street	string	-	Logradouro do cliente. Ex: Rua da Luz
customer.billing_number	string	-	Número do endereço. Ex: 1234
customer.billing_additional	string	-	Complemento do endereço (apto, casa, etc). Ex: Casa 3
customer.billing_district	string	-	Bairro do endereço. Ex: Centro
customer.billing_city	string	-	Cidade do endereço. Ex: São Paulo
customer.billing_state	string	-	UF do endereço. Ex: SP

Exemplo

{
 "id":"6dLOQgp8hquZIT0I356",
 "amount":20000,
 "checkout_url":"https://checkout.southpayments.com/checkout/6dLOQgp8hquZIT0I356/?signature=bdaeea20111209f66879e8d072951391",
 "status":"open",
 "description":"Acessórios",
 "merchant_key":"codigo-pedido",
 "sandbox":true,
 "customer":
  {
   "customer_type":0,
   "name":"João Silva",
   "email":"[e-mail]",
   "legal_number":"13182360027",
   "billing_street":"Rua Antônio Ferreira",
   "billing_number":"1250",
   "billing_additional":"Apt 1001",
   "billing_district":"Jardim Paulista",
   "billing_city":"São Paulo",
   "billing_state":"SP",
   "billing_zipcode":"53407780",
   "phone_number":"1199999999"
  }
}

RETORNO - INSUCESSO

Os motivos mais usuais para uma cobrança não ser criada com sucesso estão relacionados com problema na autenticação ou algum parâmetro ter sido enviado incorretamente (ou não enviado, no caso dos obrigatórios).

Códigos HTTP

400 - Bad Request
401 - Unauthorized
422 - Unprocessable Entity

Detalhes sobre os códigos HTTP e os motivos de insucesso estão apresentados na seção Códigos de Erro de Retorno.