Skip to content

PIX-514 create payment with network token #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
martinusso wants to merge 1 commit into
base: master
Choose a base branch
from
Open

PIX-514 create payment with network token #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 69 additions & 0 deletions .github/workflows/pr.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
name: PR

on:
pull_request:
branches:
- master

concurrency:
group: pr-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true

jobs:
unit-tests:
name: Unit tests
runs-on: ubuntu-latest
defaults:
run:
working-directory: api30.sdk

steps:
- name: Checkout
uses: actions/checkout@v4

- name: Set up Java 8
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: 8
cache: maven
cache-dependency-path: api30.sdk/pom.xml

- name: Run unit tests
run: mvn test -B

integration-tests:
name: Integration tests
runs-on: ubuntu-latest
needs: unit-tests
defaults:
run:
working-directory: api30.sdk

steps:
- name: Checkout
uses: actions/checkout@v4

- name: Set up Java 8
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: 8
cache: maven
cache-dependency-path: api30.sdk/pom.xml

- name: Validate sandbox credentials
env:
CIELO_MERCHANT_ID: ${{ secrets.CIELO_MERCHANT_ID }}
CIELO_MERCHANT_KEY: ${{ secrets.CIELO_MERCHANT_KEY }}
run: |
if [ -z "$CIELO_MERCHANT_ID" ] || [ -z "$CIELO_MERCHANT_KEY" ]; then
echo "::error::Configure os secrets CIELO_MERCHANT_ID e CIELO_MERCHANT_KEY no repositório GitHub."
exit 1
fi

- name: Run integration tests
env:
CIELO_MERCHANT_ID: ${{ secrets.CIELO_MERCHANT_ID }}
CIELO_MERCHANT_KEY: ${{ secrets.CIELO_MERCHANT_KEY }}
run: mvn verify -DskipITs=false -B
188 changes: 176 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,147 @@ SDK API-3.0 Java

## Principais recursos

* [x] Pagamentos por cartão de crédito.
* [x] Pagamentos recorrentes.
* [x] Com autorização na primeira recorrência.
* [x] Com autorização a partir da primeira recorrência.
* [x] Pagamentos por cartão de débito.
* [x] Pagamentos por boleto.
* [x] Pagamentos por transferência eletrônica.
* [x] Cancelamento de autorização.
* [x] Consulta de pagamentos.
* [x] Geração de token para o cartão para armazenamento seguro
- [x] Pagamentos por cartão de crédito.
- [x] Pagamentos recorrentes.
- [x] Com autorização na primeira recorrência.
- [x] Com autorização a partir da primeira recorrência.
- [x] Pagamentos por cartão de débito.
- [x] Pagamentos por boleto.
- [x] Pagamentos por transferência eletrônica.
- [x] Cancelamento de autorização.
- [x] Consulta de pagamentos.
- [x] Geração de token para o cartão para armazenamento seguro

## Limitações

Por envolver a interface de usuário da aplicação, o SDK funciona apenas como um framework para criação das transações. Nos casos onde a autorização é direta, não há limitação; mas nos casos onde é necessário a autenticação ou qualquer tipo de redirecionamento do usuário, o desenvolvedor deverá utilizar o SDK para gerar o pagamento e, com o link retornado pela Cielo, providenciar o redirecionamento do usuário.

## Setup (Ubuntu)

Pré-requisitos: **Java JDK 8+** e **Maven 3**.

```bash
sudo apt update
sudo apt install -y openjdk-8-jdk maven
```

Verifique a instalação:

```bash
java -version
mvn -version
```

Clone o repositório e compile o SDK:

```bash
git clone <url-do-repositorio>
cd API-3.0-Java/api30.sdk
mvn clean package
```

O artefato gerado ficará em `api30.sdk/target/api30.sdk-0.1.0.jar`.

Para usar o SDK em outro projeto Maven, instale localmente:

```bash
cd api30.sdk
mvn install
```

## Testes unitários

Os testes ficam em `api30.sdk/src/test/java` e usam JUnit 3.

Para executar todos os testes:

```bash
cd api30.sdk
mvn test
```

Para executar apenas uma classe:

```bash
cd api30.sdk
mvn -Dtest=ExternalBrandTokenTest test
```

Para executar um método específico:

```bash
cd api30.sdk
mvn -Dtest=ExternalBrandTokenTest#testPanPayloadRemainsUnchanged test
```

Se não tiver Java/Maven instalados localmente, use Docker:

```bash
docker run --rm -v "$PWD":/workspace -w /workspace/api30.sdk maven:3.9-eclipse-temurin-8 mvn test
```

## Testes de integração

Testes que chamam o **sandbox da Cielo** ficam em `api30.sdk/src/it/java` e rodam
separados dos unitários via `maven-failsafe-plugin`. Por padrão, `mvn test` e
`mvn package` **não** executam integração.

Fluxo coberto: [token de bandeira externo](https://docs.cielo.com.br/ecommerce-cielo/reference/token-bandeira-externo).

Os DPANs de teste seguem a regra do [sandbox de cartão de crédito](https://docs.cielo.com.br/ecommerce-cielo/reference/credito-sandbox): o **último dígito** define o resultado simulado. A classe usa a base `402400715376319X` (cartão de exemplo da Cielo).

| Último dígito | Cenário IT | Status esperado | ReturnCode |
| ------------- | --------------- | --------------- | ---------- |
| 1 | Autorizado | 1 | 4 ou 6 |
| 2 | Não autorizado | 3 | 05 |
| 3 | Cartão expirado | 3 | 57 |

### Variáveis de ambiente

| Variável | Obrigatória | Descrição |
| ----------------------------- | ----------- | ------------------------------------------------------------- |
| `CIELO_MERCHANT_ID` | Sim | Credencial sandbox |
| `CIELO_MERCHANT_KEY` | Sim | Credencial sandbox |
| `CIELO_TEST_CRYPTOGRAM` | Não | Criptograma de teste (padrão: valor da documentação Cielo) |
| `CIELO_TEST_BRAND` | Não | Bandeira (padrão: `Visa` na CIT, `Master` na MIT) |
| `CIELO_ISSUER_TRANSACTION_ID` | Não | Usado na MIT se a CIT autorizada não retornar o identificador |
| `CIELO_IT_VERBOSE` | Não | `true` imprime a resposta JSON completa no console |

### Executar

```bash
cd api30.sdk

export CIELO_MERCHANT_ID="seu-merchant-id-sandbox"
export CIELO_MERCHANT_KEY="sua-merchant-key-sandbox"

mvn verify -DskipITs=false
```

A classe `ExternalBrandTokenIT` executa em ordem:

1. **CIT autorizada** — DPAN terminando em `1`, valida `Status=1` e `ReturnCode` 4 ou 6.
2. **CIT negada** — DPAN terminando em `2`, valida `Status=3` e `ReturnCode=05`.
3. **CIT cartão expirado** — DPAN terminando em `3`, valida `Status=3` e `ReturnCode=57`.
4. **MIT** — reutiliza o `IssuerTransactionId` da CIT autorizada (ou `CIELO_ISSUER_TRANSACTION_ID`) sem criptograma.

Para rodar só a integração (após compilar):

```bash
cd api30.sdk
mvn failsafe:integration-test -DskipITs=false
```

Se as credenciais não estiverem configuradas, os testes de integração são
**ignorados** automaticamente.

Para ver a resposta completa da Cielo no console:

```bash
export CIELO_IT_VERBOSE=true
mvn verify -DskipITs=false
```

## Utilizando o SDK

Para criar um pagamento simples com cartão de crédito com o SDK, basta fazer:
Expand Down Expand Up @@ -86,7 +212,7 @@ try {
// // Configure o SDK com seu merchant e o ambiente apropriado para
// gerar o token
cardToken = new CieloEcommerce(merchant, Environment.SANDBOX).createCardToken(cardToken);

String generatedToken = cardToken.getCardToken();

System.out.printf("CardToken: %s\n", generatedToken);
Expand All @@ -97,6 +223,44 @@ try {
}
```

### Criando um pagamento com token de bandeira externo

O token de bandeira criado fora da Cielo deve ser informado como DPAN em
`CardNumber`. Ele não deve ser enviado em `CardToken`, pois esse campo é
reservado ao token criado pela própria Cielo.

```java
Sale sale = new Sale("ID do pagamento");
sale.customer("Comprador Teste");

Payment payment = sale.payment(15700);
payment.creditCard(null, "Visa")
.setCardNumber("DPAN GERADO PELA BANDEIRA")
.setCardNumberType(CreditCard.CardNumberType.DPAN)
.setHolder("Comprador Teste")
.setCryptogram("CRIPTOGRAMA GERADO PARA A TRANSACAO")
.setExpirationDate("12/2030");

sale = new CieloEcommerce(merchant, Environment.SANDBOX).createSale(sale);

// Armazene sempre os identificadores mais recentes para transações relacionadas.
String issuerTransactionId = sale.getPayment().getIssuerTransactionId();
String transactionLinkId = sale.getPayment().getTransactionLinkId();
```

Quem chama o SDK é responsável por decidir se deve informar o criptograma:

- Em uma transação iniciada pelo portador (CIT), informe `Cryptogram`.
- Em uma transação Mastercard iniciada pelo estabelecimento (MIT), não informe
`Cryptogram` e envie o `IssuerTransactionId` mais recente por meio de
`Payment.setIssuerTransactionId`.
- `TransactionLinkId` é retornado para transações Mastercard e deve ser
armazenado. Consulte a documentação da Cielo antes de enviá-lo em uma MIT,
pois o contrato de envio será disponibilizado antes de sua obrigatoriedade.

`SecurityCode` é opcional no pagamento com token de bandeira. Por isso, o
exemplo passa `null` ao método `creditCard`.

## Manual

Para mais informações sobre a integração com a API 3.0 da Cielo, vide o manual em: [Integração API 3.0](https://developercielo.github.io/Webservice-3.0/)
61 changes: 60 additions & 1 deletion api30.sdk/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,18 @@
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<slf4j.version>1.7.36</slf4j.version>
<junit.version>4.13.2</junit.version>
<maven.surefire.version>3.2.5</maven.surefire.version>
<maven.failsafe.version>3.2.5</maven.failsafe.version>
<build-helper.version>3.5.0</build-helper.version>
<skipITs>true</skipITs>
</properties>

<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>3.8.1</version>
<version>${junit.version}</version>
<scope>test</scope>
</dependency>
<dependency>
Expand All @@ -39,6 +44,60 @@
<scope>provided</scope>
</dependency>
</dependencies>

<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>${maven.surefire.version}</version>
<configuration>
<excludes>
<exclude>**/*IT.java</exclude>
</excludes>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>${maven.failsafe.version}</version>
<configuration>
<skipITs>${skipITs}</skipITs>
<includes>
<include>**/*IT.java</include>
</includes>
</configuration>
<executions>
<execution>
<goals>
<goal>integration-test</goal>
<goal>verify</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<version>${build-helper.version}</version>
<executions>
<execution>
<id>add-it-source</id>
<phase>generate-test-sources</phase>
<goals>
<goal>add-test-source</goal>
</goals>
<configuration>
<sources>
<source>src/it/java</source>
</sources>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>

<distributionManagement>
<snapshotRepository>
<id>nexus-snapshots</id>
Expand Down
Loading
Loading