Credit card

Article summary

Did you find this summary helpful?

Thank you for your feedback

Available in Classic and VPC

Recognize and extract key-value input information from credit cards using a specialized model engine.

Request

This section describes the request format. The method and URI are as follows:

Method	URI
POST	/credit-card

Request headers

For information about the headers common to all CLOVA OCR APIs, see CLOVA OCR request headers.

Request body

You can include the following data in the body of your request:

If `Content-Type: application/json`

You can include the following data in the body of your request if the request header's Content-Type is application/json:

Field	Type	Required	Description
`version`	String	-	Version information Only use `V2`
`requestId`	String	Required	Random API call UUID
`timestamp`	Integer	Required	Random API call time (timestamp)
`images`	Array	Required	images details

If `Content-Type: multipart/form-data`

You can include the following data in the body of your request if the request header's Content-Type is multipart/form-data:

Field	Type	Required	Description
`message`	Object	Required	Request data information
`message.version`	String	Required	Version information Only use `V2`
`message.requestId`	String	Required	Random API call UUID
`message.timestamp`	Integer	Required	Random API call time (timestamp)
`message.images`	Array	Required	images details
`file`	File	Required	OCR recognition image file

`images`

The following describes images.

Field	Type	Required	Description
`format`	String	Required	Image format `jpg` \| `jpeg` \| `png` \| `pdf` \| `tif` \| `tiff` Image: `jpg`, `jpeg`, `png` Single page: `pdf`, `tif`, `tiff` Select and enter one of the image formats
`name`	String	Required	Random image name Use to identify images and check response results
`data`	String	Required	Base64-encoded image data Can be entered if `Content-Type: application/json`

Request example

The request example is as follows:

If `Content-Type: application/json`

The request example if the request header's Content-Type is application/json is as follows:

curl --location --request POST 'https://cbgrx5natw.apigw.ntruss.com/custom/v1/{DomainId}/{InvokeKey}/document/credit-card' \
--header 'Content-Type: application/json' \
--header 'X-OCR-SECRET: {Secret key issued when registering the app}' \
--data '{
    "version": "V2",
    "requestId": "1234",
    "timestamp": "0",
    "images": [
        {
            "format": "png",
            "data": "{Base64-encoded image data}",
            "name": "creaditcard_test2"
    }]
}'

If `Content-Type: multipart/form-data`

The request example if the request header's Content-Type is multipart/form-data is as follows:

curl --location --request POST 'https://cbgrx5natw.apigw.ntruss.com/custom/v1/{DomainId}/{InvokeKey}/document/credit-card' \
--header 'X-OCR-SECRET: {Secret key issued when registering the app}' \
--header 'Content-Type: multipart/form-data' \
--form 'message="{\"version\": \"V2\", \"requestId\": \"1234\", \"timestamp\": 1724832750462, \"images\": [{\"format\": \"jpg\", \"name\": \"creditcard_test\"}]}"' \
--form '{file}.png"'

Response

This section describes the response format.

Response body

The response body includes the following data:

Field	Type	Required	Description
`version`	String	-	Version information Only use `V2`
`requestId`	String	-	Random API call UUID
`timestamp`	Integer	-	API call time (timestamp)
`images`	Array	-	images details

`images`

The following describes images.

Field	Type	Required	Description
`uid`	String	-	Credit card image UID Use for API validity checks
`name`	String	-	Credit card image name Use to identify images and check response results
`inferResult`	String	-	Credit card image recognition result `SUCCESS` \| `FAILURE` \| `ERROR` `SUCCESS`: recognition successful `FAILURE`: recognition failure `ERROR`: recognition processing exception
`message`	String	-	Result message
`validationResult`	Object	-	Validity check result information
`validationResult.result`	String	-	Validity check result code `NO_REQUESTED` \| `UNCHECKED` \| `ERROR` \| `VALID` \| `INVALID` `NO_REQUESTED`: no validation action requested (validity check failed) `UNCHECKED`: unable to verify validation `ERROR`: error on validation (validity check failed) `VALID`: validation result valid (validity check succeeded) `INVALID`: failed to pass validation
`validationResult.message`	String	-	Validity check result details message This value is not always returned
`convertedImageInfo`	Object	-	Converted image information If `format` is `pdf` or `tiff` Coordinate values are set relative to the called image file
`convertedImageInfo.width`	Integer	-	Converted image width
`convertedImageInfo.height`	Integer	-	Converted image height
`convertedImageInfo.pageIndex`	Integer	-	Converted image page index
`creditCard`	Object	-	Credit card details
`creditCard.result`	Object	-	Credit card OCR recognition result

`result`

The following describes creditCard.result.

Field	Type	Required	Description
`name`	Object	-	Card owner name details See Common object information
`number`	Object	-	Card number details See Common object information
`validThru`	Object	-	Card expiration date details See Common object information

Common object information

The following describes the common objects.

Field	Type	Required	Description
`text`	String	-	Recognized text
`confidenceScore`	Float	-	Confidence of recognized text 0 - 1 The higher the confidence value, the more accurate the text is
`boundingPoly`	Object	-	Bounding Poly information
`boudningPoly.vertices`	Array	-	Bounding Poly Vertices details
`subBoundingPolys`	Array	-	subBoundiongPolys details

`vertices`

The following describes boundingPolyVertices.

Field	Type	Required	Description
`x`	Float	-	Bounding Poly X-axis coordinate value
`y`	Float	-	Bounding Poly Y-axis coordinate value

`subBoundingPolys`

The following describes subBoundingPolys.

Field	Type	Required	Description
`x`	Float	-	Sub Bounding Poly X-axis coordinate value
`y`	Float	-	Sub Bounding Poly Y-axis coordinate value

Response status codes

For information about the HTTP status codes common to all CLOVA OCR APIs, see Common CLOVA OCR response status codes.

Response example

The response example is as follows:

Success

The following is a sample response upon a successful call.

{
    "version": "V2",
    "requestId": "1234",
    "timestamp": 1725005676747,
    "images": [
        {
            "uid": "{uid}",
            "name": "creditcard_test",
            "inferResult": "SUCCESS",
            "message": "SUCCESS",
            "validationResult": {
                "result": "NO_REQUESTED"
            },
            "creditCard": {
                "result": {
                    "name": {
                        "text": "KAIY*** VENY***",
                        "confidence": 0.8576972,
                        "boundingPoly": {
                            "vertices": []
                        },
                        "subBoundingPolys": [
                            {
                                "vertices": [
                                    {
                                        "x": 192.0,
                                        "y": 609.0
                                    },
                                    {
                                        "x": 407.0,
                                        "y": 609.0
                                    },
                                    {
                                        "x": 407.0,
                                        "y": 651.0
                                    },
                                    {
                                        "x": 192.0,
                                        "y": 651.0
                                    }
                                ]
                            } 
                        ]
                    },
                    "number": {
                        "text": "512571781234****",
                        "confidence": 0.999885,
                        "boundingPoly": {
                            "vertices": [
                                {
                                    "x": 187.0,
                                    "y": 450.0
                                },
                                {
                                    "x": 1007.0,
                                    "y": 450.0
                                },
                                {
                                    "x": 1007.0,
                                    "y": 506.0
                                },
                                {
                                    "x": 187.0,
                                    "y": 506.0
                                }
                            ]
                        },
                        "subBoundingPolys": [
                            {
                                "vertices": [
                                    {
                                        "x": 187.0,
                                        "y": 450.0
                                    },
                                    {
                                        "x": 360.0,
                                        "y": 450.0
                                    },
                                    {
                                        "x": 360.0,
                                        "y": 506.0
                                    },
                                    {
                                        "x": 187.0,
                                        "y": 506.0
                                    }
                                ]
                            },
                        ]
                    },
                    "validThru": {
                        "text": "09/23",
                        "confidence": 0.9999175,
                        "boundingPoly": {
                            "vertices": [
                                {
                                    "x": 585.0,
                                    "y": 557.0
                                },
                                {
                                    "x": 735.0,
                                    "y": 557.0
                                },
                                {
                                    "x": 735.0,
                                    "y": 600.0
                                },
                                {
                                    "x": 585.0,
                                    "y": 600.0
                                }
                            ]
                        },
                        "subBoundingPolys": []
                    }
                }
            }
        }
    ]
}

Failure

The following is a sample response upon a failed call.

{
    "version": "V2",
    "requestId": "4567",
    "timestamp": 1725003278037,
    "images": [
        {
            "uid": "{uid}",
            "name": "receipt_test2",
            "inferResult": "ERROR",
            "message": "Read page:0 error.",
            "validationResult": {
                "result": "NO_REQUESTED"
            }
        }
    ]
}

Was this article helpful?

What's Next

Receipt

Table of contents

Request
Response

Credit card

Request

Request headers

Request body

If Content-Type: application/json

If Content-Type: multipart/form-data

images

Request example

If Content-Type: application/json

If Content-Type: multipart/form-data

Response

Response body

images

result

Common object information

vertices

subBoundingPolys

Response status codes

Response example

Success

Failure

What's Next

If `Content-Type: application/json`

If `Content-Type: multipart/form-data`

`images`

If `Content-Type: application/json`

If `Content-Type: multipart/form-data`

`images`

`result`

`vertices`

`subBoundingPolys`